Sonar

API Overview

The Sonar API is a JSON based RESTful API. The API utilizes common HTTP methods such as GET, POST, PATCH and DELETE in order to identify the type of action you wish to perform. The appropriate method for each function in this API is designated alongside the documentation for the function.

Authentication is performed using basic HTTP authentication against an Sonar user account (for example, you can utilize the API using your 'admin' account.) The API is stateless and therefore sessionless. The authentication information must be sent with each API request.

Permissions for the API are inherited from the user account. When submitting a request using basic HTTP authentication, you must also include a header for Content-Type that specifies application/json. The API does not currently support any content-type other than JSON. You can also include an Accept-Encoding header that specifies application/gzip, which will help with larger queries.

There are currently not any official libraries to implement the Sonar API, but you can use any simple HTTP client/framework to interface with this API. An example for PHP would be Guzzle. You can also utilize a tool like Postman to easily test the API.

API Implementation

All multi-item responses are paginated automatically. The maximum amount of items that can be returned in a single query is 100. You may specify the number of items to be returned in the query by appending a GET parameter of limit. You may specify the page you wish to view by appending a GET parameter of page.

All responses are returned as JSON, and are formatted as follows:

{
    "data": [
        {
           "some key": "some value"
        },
        {
            "some key": "some other value"
        }
    ],
    "paginator":
    {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 2
    }
}

Only responses capable of returning more than one result will have a paginator attached. If your request can only ever return a single response, then data will not be an array, and will simply be a single object as shown below:

{
    "data": {
        "id": 3,
        "line1": "555 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

All successful responses are sent with an HTTP response code of 2xx.

If an API response fails, it will be sent with a non-2xx HTTP response code and JSON in the following format:

{
    "error":
    {
       "message": "This is what happened",
       "status_code": 4xx
    }
}

It is also possible for the message property to be an object. This will be set if the request fails to meet the required parameters. An example is shown below:

{
  "error": {
    "message": {
      "name": "The name field is required."
    },
    "status_code": 422
  }
}

This example shows that the name field was required when submitting to an endpoint. If you wish to display failure results from the API in an application, you should always check if the message field is a string or an object first.

The HTTP status codes currently returned are 404 if an item is not found, 405 if the method is not supported, 401 if the request is unauthorized, 403 if the user does not have API access or you try to access the API via HTTP rather than HTTPS and 422 if the configuration of the request is invalid. Any internal application errors will respond with a 500 code and should be reported to the Sonar support group.

You should not rely on the content of a returned message to determine whether or not an action was successful. Always use the HTTP response code. Messages may change if the language of the system changes and may also change between versions. Successful calls will always return a 2xx response code. Unsuccessful calls will always return a response code of 4xx. Server side failures will return a response code of 5xx and should be reported to us.

Parameters

In many of the examples, the URLs contain words prefixed with a colon (e.g. :account_id.) Any URL that has a word prefixed with a colon is a parameter that must be replaced, and the parameter will be described in the documentation below the URL. Any other parameters specified below the URL must be contained in the body of the JSON (e.g. when sending a PATCH, POST, or DELETE.) All GET parameters will always be contained in the URL, prefixed with a colon.

Updates

While some endpoints do allow models to be updated with partial data, you should generally always GET the existing object first, update the necessary parameters and then PATCH the entire object to the update endpoint. While some older endpoints do allow partial updates, this is not supported on most newer endpoints implemented in version 1.0 and beyond, so getting in the habit of querying and updating full objects will give you the best experience.

A note on the examples below

All the examples below show example.sonar.software as the URL - this should be replaced with the URL of your personal Sonar instance.

Large datasets and complex implementations

If you are using this API to extend Sonar to integrate with your internal systems, and you find yourself performing redundant queries, or having to query a lot of records to find the data you need, stop and contact us for assistance. We can often provide you with a solution or implement a new endpoint to make things easier for you, and scale better for your instance. If you are constantly pulling large datasets from your Sonar instance in an attempt to find specific pieces of information, you will almost certainly cause noticeable performance degradation of your instance.

Please also take note of the search endpoint - this is typically the most efficient way to find specific entries. You should not query all data and paginate the results looking for an individual item!

Support

Please note that this API is provided as a tool for you to utilize in order to extend Sonar for your own purposes. No official support is provided in regards to usage or implementation of this API, but you are welcome to contact us at support@sonar.software if you have questions or suggestions and we will provide assistance if able. The exception to this would be any bugs or security issues found - please notify us of those immediately, and they will be promptly handled.

Account Addresses

Account_Addresses - Create account address

Create a new account address

https://example.sonar.software/api/v1/accounts/:account_id/addresses

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the address to
line1	String	The first line of the address
line2 optional	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
county	String	The county, for US addresses
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 3,
        "line1": "555 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Addresses - Delete account address

Delete an account address

https://example.sonar.software/api/v1/accounts/:account_id/addresses/:address_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
address_id	Number	The ID of the address

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the address could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Account_Addresses - Get all account addresses

Get a list of the addresses for account ID :account_id

https://example.sonar.software/api/v1/accounts/:account_id/addresses

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
county	String	A valid county for the subdivision obtained from /_data/counties, null if not a US address
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "line1": "12345 Some Ln",
            "line2": "",
            "city": "West Allis",
            "state": "Wisconsin",
            "county": "Milwaukee Co.",
            "zip": "53226",
            "country": "US",
            "latitude": null,
            "longitude": null,
            "address_type_id": 1
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_Addresses - Get individual account address

Get an individual account address.

https://example.sonar.software/api/v1/accounts/:account_id/addresses/:address_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
address_id	Number	The ID of the address
county	String	A valid county for the subdivision obtained from /_data/counties, null if not a US address

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
       "line1": "12345 Some Ln",
       "line2": "",
       "city": "West Allis",
       "state": "Wisconsin",
       "county": "Milwaukee Co.",
       "zip": "53226",
       "country": "US",
       "latitude": null,
       "longitude": null,
       "address_type_id": 1
    }
}

Account_Addresses - Update account address

Update an account address.

https://example.sonar.software/api/v1/accounts/:account_id/addresses/:address_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account to update the address on
address_id	Number	The ID of the address
line1 optional	String	The first line of the address
line2 optional	String	The second line of the address, typically used for a suite number, apartment number, etc
city optional	String	The city
state optional	String	The state, province or other country subdivision
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip optional	String	The ZIP/postal code
country optional	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude optional	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude optional	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id optional	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "line1": "444 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Account Billing

Account_Billing - Get account billing details

Get some details about the accounts billing details. This is mainly used for the customer portal.

https://example.sonar.software/api/v1/accounts/:id/billing_details

Parameter

Field	Type	Description
id	Number	The internal ID of the account

Success 200

Field	Type	Description
balance_due	Number	The balance due on the account, including any child accounts
next_recurring_charge_amount	Number	The estimated amount of the next monthly recurring bill, including taxes
total_balance	Number	The balance due, plus any un-invoiced charges on the account
available_funds	Number	Any unapplied deposits (payments) or discounts on the account
next_bill_date	Date	The next date a monthly bill will be generated, can be null

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "balance_due": 586.5,
    "balance_total": 789.5,
    "next_recurring_charge_amount": 0,
    "next_bill_date": null,
    "available_funds": 123.45
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The internal ID of the account

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days before the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
due_days_day	String	Whether the `due_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
switch_status_after_delinquency	Boolean	Whether or not this account should be switched into a new inactive status after X days of delinquency.
days_of_delinquency_for_status_switch	Integer	If `switch_status_after_delinquency` is `true`, this is the number of days of delinquency to allow before switching status
delinquency_account_status_id	Integer	The account status ID to switch into after `days_of_delinquency_for_status_switch` is exceeded. Must be an inactive status.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice",
    "due_days_day": "billing",
    "switch_status_after_delinquency": false,
    "days_of_delinquency_for_status_switch": 100,
    "delinquency_account_status_id": 3
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The internal ID of the account

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days before the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
due_days_day	String	Whether the `due_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice",
    "due_days_day": "billing"
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The internal ID of the account

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days after billing that the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice"
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The internal ID of the account

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days after billing that the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice"
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The internal ID of the account

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days after billing that the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
         "bill_day": 11,
         "due_days": 10,
         "grace_days": 3,
         "grace_until": null,
         "months_to_bill": 1,
         "tax_exempt": false,
         "print_invoice": false,
         "separate_invoice_day_enabled": true,
         "invoice_day": 1
    }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The internal ID of the account

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days after billing that the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
         "bill_day": 11,
         "due_days": 10,
         "grace_days": 3,
         "grace_until": null,
         "months_to_bill": 1,
         "tax_exempt": false,
         "print_invoice": false
    }
}

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The ID of the account to update
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days before the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
prorate	Boolean	Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
due_days_day	String	Whether the `due_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
switch_status_after_delinquency	Boolean	Whether or not this account should be switched into a new inactive status after X days of delinquency.
days_of_delinquency_for_status_switch	Integer	If `switch_status_after_delinquency` is `true`, this is the number of days of delinquency to allow before switching status
delinquency_account_status_id	Integer	The account status ID to switch into after `days_of_delinquency_for_status_switch` is exceeded. Must be an inactive status.

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days before the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
due_days_day	String	Whether the `due_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
switch_status_after_delinquency	Boolean	Whether or not this account should be switched into a new inactive status after X days of delinquency.
days_of_delinquency_for_status_switch	Integer	If `switch_status_after_delinquency` is `true`, this is the number of days of delinquency to allow before switching status
delinquency_account_status_id	Integer	The account status ID to switch into after `days_of_delinquency_for_status_switch` is exceeded. Must be an inactive status.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice",
    "due_days_day": "billing",
    "switch_status_after_delinquency": false,
    "days_of_delinquency_for_status_switch": 100,
    "delinquency_account_status_id": 3
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The ID of the account to update
bill_day optional	Number	The day of the month that the account bills
due_days optional	Number	The number of days before the invoice becomes past due
grace_days optional	Number	The number of days after the invoice is past due that penalties are applied
grace_until optional	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill optional	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt optional	Boolean	Whether or not the account is tax exempt
prorate optional	Boolean	Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default
print_invoice optional	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled optional	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day optional	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days optional	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode optional	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day optional	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
due_days_day optional	String	Whether the `due_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days before the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`
due_days_day	String	Whether the `due_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice",
    "due_days_day": "billing"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The ID of the account to update
bill_day optional	Number	The day of the month that the account bills
due_days optional	Number	The number of days after billing that the invoice becomes past due
grace_days optional	Number	The number of days after the invoice is past due that penalties are applied
grace_until optional	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill optional	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt optional	Boolean	Whether or not the account is tax exempt
prorate optional	Boolean	Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default
print_invoice optional	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled optional	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day optional	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days optional	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode optional	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day optional	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days after billing that the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`
auto_pay_day	String	Whether the `auto_pay_days` value is counted from the billing date or the invoice date. Only applies if `separate_invoice_day_enabled` is `true`. Allowed values: `"billing"`, `"invoice"`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The ID of the account to update
bill_day optional	Number	The day of the month that the account bills
due_days optional	Number	The number of days after billing that the invoice becomes past due
grace_days optional	Number	The number of days after the invoice is past due that penalties are applied
grace_until optional	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill optional	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt optional	Boolean	Whether or not the account is tax exempt
prorate optional	Boolean	Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default
print_invoice optional	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled optional	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day optional	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days optional	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode optional	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days after billing that the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.
auto_pay_days	Number	The number of days after automatic invoice generation that any auto-pay methods are charged
bill_mode	String	Whether the user receives an invoice or a statement Allowed values: `"invoice"`, `"statement"`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The ID of the account to update
bill_day optional	Number	The day of the month that the account bills
due_days optional	Number	The number of days after billing that the invoice becomes past due
grace_days optional	Number	The number of days after the invoice is past due that penalties are applied
grace_until optional	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill optional	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt optional	Boolean	Whether or not the account is tax exempt
prorate optional	Boolean	Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default
print_invoice optional	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled optional	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day optional	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days after billing that the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice
separate_invoice_day_enabled	Boolean	Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs
invoice_day	Number	If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
         "bill_day": 11,
         "due_days": 10,
         "grace_days": 3,
         "grace_until": null,
         "months_to_bill": 1,
         "tax_exempt": false,
         "print_invoice": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field	Type	Description
id	Number	The ID of the account to update
bill_day optional	Number	The day of the month that the account bills
due_days optional	Number	The number of days after billing that the invoice becomes past due
grace_days optional	Number	The number of days after the invoice is past due that penalties are applied
grace_until optional	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill optional	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt optional	Boolean	Whether or not the account is tax exempt
prorate optional	Boolean	Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default
print_invoice optional	Boolean	Whether or not the account receives a printed invoice

Success 200

Field	Type	Description
bill_day	Number	The day of the month that the account bills
due_days	Number	The number of days after billing that the invoice becomes past due
grace_days	Number	The number of days after the invoice is past due that penalties are applied
grace_until	Date	A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset
months_to_bill	Number	The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges
tax_exempt	Boolean	Whether or not the account is tax exempt
print_invoice	Boolean	Whether or not the account receives a printed invoice

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
         "bill_day": 11,
         "due_days": 10,
         "grace_days": 3,
         "grace_until": null,
         "months_to_bill": 1,
         "tax_exempt": false,
         "print_invoice": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account Call Logs

Account_Call_Logs - Create a new call log

Create a new call log.

https://example.sonar.software/api/v1/accounts/:id/call_logs

Parameter

Field	Type	Description
id	Number	The ID of the account
time_in_seconds	Number	How long the call lasted, in seconds
subject	String	The subject of the call
body	String	A longer description of the call

Success 200

Field	Type	Description
id	Number	The ID of the call log.
account_id	Number	The ID of the account
time_in_seconds	Number	How long the call lasted, in seconds
subject	String	The subject of the call
body	String	A longer description of the call
user_id	Number	The ID of the user who created the call log
created_at	DateTime	The date and time the call log was created in UTC

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "account_id": 2,
    "time_in_seconds": 12,
    "subject": "Support issue",
    "body": "Blah blah blah blah blah",
    "user_id": 1,
    "created_at": "2016-05-20 14:14:33"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "time_in_seconds": "The time_in_seconds must be an integer."
     },
     "status_code": 422
   }
 }

Account_Call_Logs - Delete a call log

Delete a call log. Requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:id/call_logs/:call_log_id

Parameter

Field	Type	Description
id	Number	The account ID
call_log_id	Number	The call log ID

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the call log could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Call log does not exist.",
         "status_code": 404
     }
 }

Account_Call_Logs - Get all call logs

Get all call logs

https://example.sonar.software/api/v1/accounts/:id/call_logs

Parameter

Field	Type	Description
id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the call log.
account_id	Number	The ID of the account
time_in_seconds	Number	How long the call lasted, in seconds
subject	String	The subject of the call
body	String	A longer description of the call
user_id	Number	The ID of the user who created the call log
created_at	DateTime	The date and time the call log was created in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "account_id": 2,
      "time_in_seconds": 12,
      "subject": "Support issue",
      "body": "Blah blah blah blah blah",
      "user_id": 1,
      "created_at": "2016-05-20 14:14:33"
    },
    {
      "id": 2,
      "account_id": 2,
      "time_in_seconds": 12,
      "subject": "Support issue",
      "body": "Blah blah blah blah blah again!",
      "user_id": 1,
      "created_at": "2016-05-20 14:14:33"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Call_Logs - Get an individual call log

Get an individual call log

https://example.sonar.software/api/v1/accounts/:id/call_logs/:call_log_id

Parameter

Field	Type	Description
id	Number	The ID of the account
call_log_id	Number	The ID of the call log

Success 200

Field	Type	Description
id	Number	The ID of the call log.
account_id	Number	The ID of the account
time_in_seconds	Number	How long the call lasted, in seconds
subject	String	The subject of the call
body	String	A longer description of the call
user_id	Number	The ID of the user who created the call log
created_at	DateTime	The date and time the call log was created in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "account_id": 2,
    "time_in_seconds": 12,
    "subject": "Support issue",
    "body": "Blah blah blah blah blah",
    "user_id": 1,
    "created_at": "2016-05-20 14:14:33"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_Call_Logs - Update call log

Update an existing call log. Requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:id/call_logs/:call_log_id

Parameter

Field	Type	Description
id	Number	The account ID
call_log_id	Number	The call log ID
time_in_seconds optional	Number	How long the call lasted, in seconds
subject optional	String	The subject of the call
body optional	String	The body of the call

Success 200

Field	Type	Description
id	Number	The ID of the call log.
account_id	Number	The ID of the account
time_in_seconds	Number	How long the call lasted, in seconds
subject	String	The subject of the call
body	String	A longer description of the call
user_id	Number	The ID of the user who created the call log
created_at	DateTime	The date and time the call log was created in UTC

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "account_id": 2,
    "time_in_seconds": 12,
    "subject": "Support issue",
    "body": "Please don't write 'blah blah blah blah blah' in call logs.",
    "user_id": 1,
   "created_at": "2016-05-20 14:14:33"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account Call Records

Account_Call_Records - Get account call records

Get a list of call records on the account, between :start_date and :end_date, in YYYY-MM-DD format. The dates are checked in UTC (as call records are stored/entered with UTC.) For example, if you want to see all calls on 2016-08-01 UTC, you should enter 2016-08-01 as the start and 2016-08-02 as the end.

https://example.sonar.software/api/v1/accounts/:account_id/call_records/:start_date/:end_date

Parameter

Field	Type	Description
account_id	Number	The ID of the account
start_date	Date	The start date, in UTC. YYYY-MM-DD format.
end_date	Date	The end date, in UTC. YYYY-MM-DD format.
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the call record
origination	String	The originating DID
destination	String	The destination DID
call_start	DateTime	The call start, in UTC
duration_in_seconds	Integer	The length of the call, in seconds
matched_prefix	String	The prefix that was matched for billing
prefix_name	String	A descriptive name for the prefix match
rate	Number	The rate, to 20 decimal places
local	Boolean	Whether or not the call was rated as local
long_distance	Boolean	Whether or not the call was rated as long distance
service_id	Integer	The service ID this call was rated against

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 8,
      "origination": "14145132472",
      "destination": "18007776666",
      "call_start": "2016-08-26 16:09:46",
      "duration_in_seconds": 1999,
      "matched_prefix": "1800",
      "prefix_name": "TOLL FREE",
      "rate": "0.00000000000000000000",
      "local": false,
      "long_distance": false,
      "service_id": 5
    },
    {
      "id": 7,
      "origination": "14145132472",
      "destination": "011376312341231234",
      "call_start": "2016-08-26 16:09:46",
      "duration_in_seconds": 154,
      "matched_prefix": "3763",
      "prefix_name": "ANDORRA",
      "rate": "0.36400000000000000000",
      "local": false,
      "long_distance": false,
      "service_id": 5
    }
  ],
  "paginator": {
    "total_count": 8,
    "total_pages": 4,
    "current_page": 1,
    "limit": 2
  }
}

Account Contacts

Account_Contacts - Create account contact

Create a new account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts

Parameter

Field	Type	Description
account_id	Number	The ID of the account
name	String	The name of the contact
role optional	String	The role of the contact
email_address optional	String	The email address of the contact
phone_numbers optional	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts
username optional	String	A username for the customer portal. Required if password is set.
password optional	String	A password for the customer portal. Required if username is set.

Success 200

Field	Type	Description
id	Number	The ID of the contact
name	String	The name of the contact
role	String	The role of the contact
email_address	String	The email address of the contact
phone_numbers	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact
username	String	A username for the customer portal

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
       "email_message_categories": [
           2
       ],
       "primary": true,
       "username": "babymonkey"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name field is required.",
         },
         "status_code": 422
     }
 }

Account_Contacts - Create account contact

Create a new account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts

Parameter

Field	Type	Description
account_id	Number	The ID of the account
name	String	The name of the contact
role optional	String	The role of the contact
email_address optional	String	The email address of the contact
phone_numbers optional	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

Success 200

Field	Type	Description
id	Number	The ID of the contact
name	String	The name of the contact
role	String	The role of the contact
email_address	String	The email address of the contact
phone_numbers	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
       "email_message_categories": [
           2
       ],
       "primary": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The number field must be a number.",
         },
         "status_code": 422
     }
 }

Account_Contacts - Delete account contact

Delete an account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
contact_id	Number	The ID of the contact

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "Contact deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the contact could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "That contact ID does not exist.",
         "status_code": 404
     }
 }

Account_Contacts - Get all account contacts

Get the contacts for an account

https://example.sonar.software/api/v1/accounts/:account_id/contacts

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the contact
name	String	The name of the contact
role	String	The role of the contact
email_address	String	The email address of the contact
phone_numbers	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact
username	String	The username this contact has setup for the customer portal

Success-Response:

{
    "data": [
        {
            "id": 1,
            "name": "Simon Westlake",
            "role": "CEO",
            "email_address": "simon@sonar.software",
            "phone_numbers": {
                "work": {
                    "number": "1231231234",
                    "extension": 123
                },
                "mobile": {
                    "number": "4148675309",
                    "extension": null
                }
            },
            "email_message_categories": [
                2
            ],
            "primary": true,
            "username": "leethacker12345"
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_Contacts - Get all account contacts

Get the contacts for an account

https://example.sonar.software/api/v1/accounts/:account_id/contacts

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the contact
name	String	The name of the contact
role	String	The role of the contact
email_address	String	The email address of the contact
phone_numbers	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact

Success-Response:

{
    "data": [
        {
            "id": 1,
            "name": "Simon Westlake",
            "role": "CEO",
            "email_address": "simon@sonar.software",
            "phone_numbers": {
                "work": {
                    "number": "1231231234",
                    "extension": 123
                },
                "mobile": {
                    "number": "4148675309",
                    "extension": null
                }
            },
            "email_message_categories": [
                2
            ],
            "primary": true
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_Contacts - Get individual account contact

Get an individual account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
contact_id	Number	The ID of the contact

Success 200

Field	Type	Description
id	Number	The ID of the contact
name	String	The name of the contact
role	String	The role of the contact
email_address	String	The email address of the contact
phone_numbers	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact
username	String	The username this contact has setup for the customer portal

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
        "email_message_categories": [
           2
        ],
       "primary": true,
       "username": null
    }
}

Account_Contacts - Get individual account contact

Get an individual account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
contact_id	Number	The ID of the contact

Success 200

Field	Type	Description
id	Number	The ID of the contact
name	String	The name of the contact
role	String	The role of the contact
email_address	String	The email address of the contact
phone_numbers	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
        "email_message_categories": [
           2
        ],
       "primary": true
    }
}

Account_Contacts - Update account contact

Update an account contact.

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
contact_id	Number	The ID of the contact
name optional	String	The name of the contact
role optional	String	The role of the contact
email_address optional	String	The email address of the contact
phone_numbers optional	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories optional	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary optional	Boolean	Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts
username optional	String	A username for the customer portal.
password optional	String	A password for the customer portal. Required if username is currently null, as you are creating a new account.

Success 200

Field	Type	Description
id	Number	The ID of the contact
name	String	The name of the contact
role	String	The role of the contact
email_address	String	The email address of the contact
phone_numbers	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts
username	String	The username for the customer portal

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
       "email_message_categories": [
           2
       ],
       "primary": false,
       "username": "ridingonapig"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name field is required.",
         },
         "status_code": 422
     }
 }

Account_Contacts - Update account contact

Update an account contact.

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
contact_id	Number	The ID of the contact
name optional	String	The name of the contact
role optional	String	The role of the contact
email_address optional	String	The email address of the contact
phone_numbers optional	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

Success 200

Field	Type	Description
id	Number	The ID of the contact
name	String	The name of the contact
role	String	The role of the contact
email_address	String	The email address of the contact
phone_numbers	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.
primary	Boolean	Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
       "email_message_categories": [
           2
       ]
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The number field must be a number.",
         },
         "status_code": 422
     }
 }

Account DIDs

Account_DIDs - Assign a DID to an account

Assign a currently unassigned DID to an account.

https://example.sonar.software/api/v1/accounts/:account_id/dids

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
did	String	The DID to assign. This DID must already have been inventoried in Sonar.
service_id	Integer	The ID of a voice service to associate the DID with. This voice service must already be on the account.

Success 200

Field	Type	Description
id	Number	The ID of the DID.
did	String	The DID
service_id	Integer	The ID of the voice service.
rate_center_id	Integer	The ID of the rate center that the DID is in

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "did": "1234567892",
    "account_id": 1,
    "service_id": 30,
    "rate_center_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
  "error": {
    "message": "DID is already assigned to account 1.",
    "status_code": 422
  }
}

Account_DIDs - Get all DIDs assigned to account

Get all DIDs assigned to the account.

https://example.sonar.software/api/v1/accounts/:account_id/dids

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the DID.
did	String	The DID
service_id	Integer	The ID of the voice service.
rate_center_id	Integer	The ID of the rate center that the DID is in

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 7,
      "did": "1234567892",
      "account_id": 1,
      "service_id": 30,
      "rate_center_id": 1
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_DIDs - Get an individual DID assigned to an account

Get an individual DID associated with an account.

https://example.sonar.software/api/v1/accounts/:account_id/dids/:did_id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
did_id	Integer	The ID of the DID

Success 200

Field	Type	Description
id	Number	The ID of the DID.
did	String	The DID
service_id	Integer	The ID of the voice service.
rate_center_id	Integer	The ID of the rate center that the DID is in

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "did": "1234567892",
    "account_id": 1,
    "service_id": 30,
    "rate_center_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_DIDs - Move a DID to another voice service

Update an existing DID assignment to change the assigned service

https://example.sonar.software/api/v1/accounts/:account_id/dids/:did_id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
did_id	Integer	The ID of the DID
service_id	Integer	The ID of a voice service on the account

Success 200

Field	Type	Description
id	Number	The ID of the DID.
did	String	The DID
service_id	Integer	The ID of the voice service.
rate_center_id	Integer	The ID of the rate center that the DID is in

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 7,
    "did": "1234567892",
    "account_id": 1,
    "service_id": 31,
    "rate_center_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_DIDs - Unassign a DID from an account

Unassociate a DID from an account.

https://example.sonar.software/api/v1/accounts/:account_id/dids/:did_id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
did_id	Integer	The ID of the DID

Success 200

Field	Type	Description
id	Number	The ID of the DID.
did	String	The DID
service_id	Integer	The ID of the voice service.
rate_center_id	Integer	The ID of the rate center that the DID is in

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "did": "1234567892",
    "account_id": null,
    "service_id": null,
    "rate_center_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the rate center could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account Data Usage

Account_Data_Usage - Add additional capacity to an account

Add additional capacity for an account. This is a temporary top off for the current billing period. The account must have a data service with a usage based billing policy associated with it. The policy must be configured to allow additional capacity to be added.

https://example.sonar.software/api/v1/accounts/:id/top_off

Parameter

Field Type Description

Number

The ID of the account

quantity

Number

The number of 'top offs' to apply. For example, if the overage service on the usage based billing policy defines 5 gigabytes as one unit, setting this to 2 would add 10 gigabytes.

Default value: 1

Success 200

Field	Type	Description
bytes_added	String	The number of bytes added

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "bytes_added": 5000000000
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "The account does not have a data service with a usage based billing policy.",
     "status_code": 422
   }
 }

Account_Data_Usage - Add bulk granular data usage to many accounts

Add granular data usage to many accounts. This will contribute to the accounts overall data usage, and will be added to billable/free usage. The max size of this batch is 5000, please split into smaller chunks if you have more data.

https://example.sonar.software/api/v1/accounts/bulk_granular_data_usage

Example of submitting data usage


{
    "data": [
        {
            "timestamp": 1451606400,
            "in": 1,
            "out": 3,
            "data_source_identifier": "192.168.100.123",
            "data_source_parent": "Router-01-Example.sonar.software",
            "data_type": "Unknown",
            "account_id": 12
        },
        {
            "timestamp": 1451606460,
            "in": 141,
            "out": 1807,
            "data_source_identifier": "192.168.100.123",
            "data_source_parent": "Router-01-Example.sonar.software",
            "data_type": "Unknown",
            "account_id": 4938
        }
    ]
 }

Parameter

Field	Type	Description
id	Number	The ID of the account
data	Array	An array of data to be stored, the format of which is described below this entry.
timestamp	Number	A Unix timestamp (e.g. 1465238009) with up to microsecond accuracy.
in	Number	An integer representing the number of bytes of inbound traffic to store for this timestamp. This should be a counter (e.g. it should increase above the previous value) and not a gauge (the difference from the last value to this one.) If this value is less than the prior value, it will be treated as a counter wrap and discarded.
out	Number	An integer representing the number of bytes of outbound traffic to store for this timestamp. This should be a counter (e.g. it should increase above the previous value) and not a gauge (the difference from the last value to this one.) If this value is less than the prior value, it will be treated as a counter wrap and discarded.
data_source_identifier	String	A unique identifier for the source of this data. For example, this may be an IP address, a RADIUS username, or some other unique piece of information that signifies what specific source generated this traffic.
data_source_parent	String	A unique identifier for the device that provided this data. For example, this may reference a RADIUS server, or some type of inline device.
data_type	String	The type of data (e.g. HTTP, SSH, ICMP) - you can submit something generic like 'Unknown' if you don't track the type of data being used.
account_id	Integer	The ID of the account this data should be added to

Success 200

Field	Type	Description
success	String	This will return `true` on success. If you want to get the data, use the GET endpoint.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "data.0.in": "The data.0.in must be a number."
     },
     "status_code": 422
   }
 }

Account_Data_Usage - Add granular data usage to an account

Add granular data usage to an account. This will contribute to the accounts overall data usage, and will be added to billable/free usage. The max size of this batch is 5000, please split into smaller chunks if you have more data.

https://example.sonar.software/api/v1/accounts/:id/granular_data_usage

Example of submitting data usage


{
    "data": [
        {
            "timestamp": 1451606400,
            "in": 1,
            "out": 3,
            "data_source_identifier": "192.168.100.123",
            "data_source_parent": "Router-01-Example.sonar.software",
            "data_type": "Unknown"
        },
        {
            "timestamp": 1451606460,
            "in": 141,
            "out": 1807,
            "data_source_identifier": "192.168.100.123",
            "data_source_parent": "Router-01-Example.sonar.software",
            "data_type": "Unknown"
        }
    ]
 }

Parameter

Field	Type	Description
id	Number	The ID of the account
data	Array	An array of data to be stored, the format of which is described below this entry.
timestamp	Number	A Unix timestamp (e.g. 1465238009) with up to microsecond accuracy.
in	Number	An integer representing the number of bytes of inbound traffic to store for this timestamp. This should be a counter (e.g. it should increase above the previous value) and not a gauge (the difference from the last value to this one.) If this value is less than the prior value, it will be treated as a counter wrap and discarded.
out	Number	An integer representing the number of bytes of outbound traffic to store for this timestamp. This should be a counter (e.g. it should increase above the previous value) and not a gauge (the difference from the last value to this one.) If this value is less than the prior value, it will be treated as a counter wrap and discarded.
data_source_identifier	String	A unique identifier for the source of this data. For example, this may be an IP address, a RADIUS username, or some other unique piece of information that signifies what specific source generated this traffic.
data_source_parent	String	A unique identifier for the device that provided this data. For example, this may reference a RADIUS server, or some type of inline device.
data_type	String	The type of data (e.g. HTTP, SSH, ICMP) - you can submit something generic like 'Unknown' if you don't track the type of data being used.

Success 200

Field	Type	Description
success	String	This will return `true` on success. If you want to get the data, use the GET endpoint.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "data.0.in": "The data.0.in must be a number."
     },
     "status_code": 422
   }
 }

Account_Data_Usage - Get all aggregated data usage for an account

Get the aggregated data usage for an account, split into billing periods.

https://example.sonar.software/api/v1/accounts/:id/data_usage_histories

Parameter

Field	Type	Description
id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the data usage history
billable_in_bytes	Number	The number of billable inbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.
billable_out_bytes	Number	The number of billable outbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.
free_in_bytes	Number	The number of free inbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.
free_out_bytes	Number	The number of free outbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.
start_time	DateTime	When the data began to be aggregated (UTC)
closed_time	DateTime	When the data aggregation was stopped for this item (UTC.) If null, this data is still open and is for the current billing period.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": [
    {
      "id": 136,
      "billable_in_bytes": 0,
      "billable_out_bytes": 0,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-06-25 00:51:18",
      "closed_time": null
    },
    {
      "id": 128,
      "billable_in_bytes": 6000000000,
      "billable_out_bytes": 6000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-05-25 00:49:48",
      "closed_time": "2016-06-25 00:51:18"
    },
    {
      "id": 127,
      "billable_in_bytes": 5000000000,
      "billable_out_bytes": 5000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-04-25 00:49:48",
      "closed_time": "2016-05-25 00:49:48"
    },
    {
      "id": 126,
      "billable_in_bytes": 4000000000,
      "billable_out_bytes": 4000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-03-25 00:49:48",
      "closed_time": "2016-04-25 00:49:48"
    },
    {
      "id": 125,
      "billable_in_bytes": 3000000000,
      "billable_out_bytes": 3000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-02-25 00:49:48",
      "closed_time": "2016-03-25 00:49:48"
    },
    {
      "id": 124,
      "billable_in_bytes": 2000000000,
      "billable_out_bytes": 2000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-01-25 00:49:48",
      "closed_time": "2016-02-25 00:49:48"
    },
    {
      "id": 123,
      "billable_in_bytes": 1000000000,
      "billable_out_bytes": 1000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2015-12-25 00:49:48",
      "closed_time": "2016-01-25 00:49:48"
    }
  ],
  "paginator": {
    "total_count": 7,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Data_Usage - Get an individual aggregated data usage period for an account

Get the aggregated data usage for an account, by ID.

https://example.sonar.software/api/v1/accounts/:id/data_usage_histories/:data_usage_history_id

Parameter

Field	Type	Description
id	Number	The ID of the account
data_usage_history_id	Number	The ID of the data usage history

Success 200

Field	Type	Description
id	Number	The ID of the data usage history
billable_in_bytes	Number	The number of billable inbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.
billable_out_bytes	Number	The number of billable outbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.
free_in_bytes	Number	The number of free inbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.
free_out_bytes	Number	The number of free outbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.
start_time	DateTime	When the data began to be aggregated (UTC)
closed_time	DateTime	When the data aggregation was stopped for this item (UTC.) If null, this data is still open and is for the current billing period.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 136,
    "billable_in_bytes": 0,
    "billable_out_bytes": 0,
    "free_in_bytes": 0,
    "free_out_bytes": 0,
    "start_time": "2016-06-25 00:51:18",
    "closed_time": null
  }
}

Account_Data_Usage - Get granular account data usage across a time period

Get data usage on an account between two Unix timestamps (seconds since epoch.) Unlike most multi-entry endpoints, data from this endpoint is not paginated, to make consumption of data easier for things like graphing. Data returned from this endpoint will calculate the rate of change over a specific period of time, which is the difference in seconds between the two timestamps, divided by 400 (a mostly arbitrary number chosen to make graphing reasonable, and to keep the query load down.) For example, if you input a time period of 24 hours, the difference in seconds would be 86,400. Divided by 400, this would give 216 seconds rounded up, so you would be provided with 400 data points, showing the rate of change every 1 second in 216 second increments. This endpoint returns an array of series - the success section below describes each series. The data may contain multiple series. Note that the granular data is output in bits rather than bytes for use in typical graphing applications! The total data is output in bytes.

https://example.sonar.software/api/v1/accounts/:id/granular_data_usage/:start_time/:end_time

Parameter

Field	Type	Description
id	Number	The ID of the account.
start_time	Number	A Unix timestamp (e.g. 1465238009) with up to microsecond accuracy.
end_time	Number	A Unix timestamp (e.g. 1465238010) with up to microsecond accuracy.

Success 200

Field	Type	Description
granular	Object	The granular data, broken down by time. This exists at the top level of the response object. The descriptions below are within this array, until the 'separate' array.
series	Array	An array that contains the data broken down by series. This is within the granular object.
data_source_identifier	String	A unique identifier for the source of this data. For example, this may be an IP address, a RADIUS username, or some other unique piece of information that signifies what specific source generated this traffic.
data_source_parent	String	A unique identifier for the device that provided this data. For example, this may reference a RADIUS server, or some type of inline device.
data_type	String	The type of data (e.g. HTTP, SSH, ICMP) - typically, this will be the localized string 'Unknown', unless you are feeding in more specific data categories.
in	Object	An object where the property is a Unix timestamp, and the value is the amount of data inbound in bits. If your rate of change window is greater than a minute, it is possible that these values will be floats due to the mathematical calculations performed to calculate the rate of change. Please note that the data is the rate of change between the last reading and the current one, and Sonar will attempt to keep the number of entries at 400, so values will change as the window size changes. The most granular spacing returned is 1 minute, so for the most precise data, you can request it in 400 minute windows.
out	Object	An object where the property is a Unix timestamp timestamp, and the value is the amount of data outbound in bits. If your rate of change window is greater than a minute, it is possible that these values will be floats due to the mathematical calculations performed to calculate the rate of change. Please note that the data is the rate of change between the last reading and the current one, and Sonar will attempt to keep the number of entries at 400, so values will change as the window size changes. The most granular spacing returned is 1 minute, so for the most precise data, you can request it in 400 minute windows.
totals	Object	Totals for all the data in the series array. The values below are in this object.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "granular": {
      "series": [
        {
          "data_source_identifier": "145.214.83.54",
          "data_source_parent": "Anderson-Vandervort",
          "data_type": "Call of Duty",
          "in": {
            "1467080758": 0,
            "1467081996": 0,
            "1467083234": 0,
            "1467084472": 0,
            "1467085710": 0,
            "1467086948": 0,
            "1467088186": 0,
            "1467089424": 0,
            "1467090662": 0,
            "1467091900": 0,
            "1467093138": 0,
            "1467094376": 0,
            "1467095614": 0,
            "1467096852": 0,
            "1467098090": 0,
            "1467099328": 0,
            "1467100566": 0,
            "1467101804": 217138288,
            "1467103042": 145308376,
            "1467104280": 307148776,
            "1467105518": 544508376,
            "1467106756": 0,
            "1467107994": 420432560,
            "1467109232": 0,
            "1467110470": 109454664,
            "1467111708": 182808536,
            "1467112946": 158426472,
            "1467114184": 819848064,
            "1467115422": 0,
            "1467117898": 301536480,
            "1467119136": 0,
            "1467120374": 722331496,
            "1467121612": 827977224,
            "1467124088": 110407840,
            "1467125326": 762285888,
            "1467126564": 861812776,
            "1467129040": 285242608,
            "1467130278": 911441656,
            "1467131516": 0,
            "1467132754": 660007232,
            "1467135230": 138487544,
            "1467136468": 545750880,
            "1467138944": 0,
            "1467140182": 32555352,
            "1467141420": 0,
            "1467143896": 400100064,
            "1467146372": 0,
            "1467147610": 821975776,
            "1467148848": 151347480,
            "1467150086": 0,
            "1467151324": 572727688,
            "1467152562": 0,
            "1467153800": 0,
            "1467155038": 228804672,
            "1467156276": 0,
            "1467157514": 807192432,
            "1467158752": 996707992,
            "1467159990": 777985992,
            "1467161228": 0,
            "1467162466": 295126192,
            "1467164942": 881194744,
            "1467166180": 942820872,
            "1467167418": 880257936,
            "1467168656": 0,
            "1467169894": 0,
            "1467171132": 396878992,
            "1467172370": 279056800,
            "1467173608": 111492104,
            "1467174846": 819713520,
            "1467176084": 975066904,
            "1467177322": 980927904,
            "1467178560": 619864240,
            "1467182274": 344976544,
            "1467183512": 920085688,
            "1467184750": 0,
            "1467187226": 664613584,
            "1467188464": 0,
            "1467189702": 33572808,
            "1467190940": 0,
            "1467192178": 641773848,
            "1467194654": 241669080,
            "1467195892": 126998536,
            "1467198368": 784293832,
            "1467199606": 966677656,
            "1467200844": 0,
            "1467202082": 677646040,
            "1467203320": 1012206728,
            "1467204558": 439831432,
            "1467205796": 0,
            "1467207034": 49039992,
            "1467208272": 195231264,
            "1467209510": 873323560,
            "1467210748": 856915632,
            "1467211986": 0,
            "1467213224": 0,
            "1467215700": 79292928,
            "1467216938": 713658056,
            "1467218176": 0,
            "1467219414": 685737920,
            "1467220652": 0,
            "1467221890": 0,
            "1467223128": 360265952,
            "1467224366": 0,
            "1467225604": 434273728,
            "1467226842": 0,
            "1467228080": 216324504,
            "1467229318": 0,
            "1467230556": 851006360,
            "1467233032": 334718240,
            "1467234270": 854355168,
            "1467235508": 779245856,
            "1467236746": 0,
            "1467237984": 0,
            "1467239222": 0,
            "1467240460": 542660304,
            "1467241698": 782791880,
            "1467242936": 763122896,
            "1467244174": 408041888,
            "1467245412": 0,
            "1467246650": 363461488,
            "1467247888": 0,
            "1467249126": 0,
            "1467251602": 702242904,
            "1467252840": 665581824,
            "1467254078": 912337056,
            "1467255316": 607106448,
            "1467256554": 212773648,
            "1467259030": 253847088,
            "1467260268": 272247312,
            "1467261506": 889458392,
            "1467262744": 0,
            "1467265220": 984081728,
            "1467267696": 0,
            "1467268934": 580968592,
            "1467270172": 891309648,
            "1467272648": 0,
            "1467273886": 247251968,
            "1467275124": 0,
            "1467276362": 676973864,
            "1467277600": 1005099440,
            "1467278838": 928361760,
            "1467280076": 627488416,
            "1467281314": 1011717416,
            "1467283790": 0,
            "1467285028": 524871776,
            "1467286266": 663324224,
            "1467288742": 342366880,
            "1467291218": 877844064,
            "1467292456": 663320864,
            "1467293694": 884311608,
            "1467296170": 0,
            "1467297408": 1041119216,
            "1467298646": 897873392,
            "1467301122": 0,
            "1467302360": 0,
            "1467303598": 801878496,
            "1467304836": 903899368,
            "1467307312": 0,
            "1467309788": 256131072,
            "1467311026": 225189000,
            "1467312264": 92491960,
            "1467313502": 774727352,
            "1467314740": 975401880,
            "1467315978": 885190984,
            "1467319692": 0,
            "1467320930": 0,
            "1467322168": 0,
            "1467323406": 0,
            "1467324644": 0,
            "1467325882": 0,
            "1467327120": 0,
            "1467328358": 0,
            "1467329596": 0,
            "1467330834": 0,
            "1467332072": 0,
            "1467333310": 0,
            "1467334548": 0,
            "1467335786": 0,
            "1467337024": 0,
            "1467338262": 0,
            "1467339500": 0,
            "1467340738": 0,
            "1467341976": 0,
            "1467343214": 0,
            "1467344452": 0,
            "1467345690": 0,
            "1467346928": 0,
            "1467348166": 0,
            "1467349404": 0,
            "1467350642": 0,
            "1467351880": 0,
            "1467353118": 0,
            "1467354356": 0,
            "1467355594": 0,
            "1467356832": 0,
            "1467358070": 0,
            "1467359308": 0,
            "1467360546": 0,
            "1467361784": 0,
            "1467363022": 0,
            "1467364260": 0,
            "1467365498": 0,
            "1467366736": 0,
            "1467367974": 0,
            "1467369212": 0,
            "1467370450": 0,
            "1467371688": 0,
            "1467372926": 0,
            "1467374164": 0,
            "1467375402": 0,
            "1467376640": 0,
            "1467377878": 0,
            "1467379116": 0,
            "1467380354": 0,
            "1467381592": 0,
            "1467382830": 0,
            "1467384068": 0,
            "1467385306": 0,
            "1467386544": 0,
            "1467387782": 0,
            "1467389020": 0,
            "1467390258": 0
          },
          "out": {
            "1467080758": 0,
            "1467081996": 0,
            "1467083234": 0,
            "1467084472": 0,
            "1467085710": 0,
            "1467086948": 0,
            "1467088186": 0,
            "1467089424": 0,
            "1467090662": 0,
            "1467091900": 0,
            "1467093138": 0,
            "1467094376": 0,
            "1467095614": 0,
            "1467096852": 0,
            "1467098090": 0,
            "1467099328": 0,
            "1467100566": 0,
            "1467101804": 23459856,
            "1467103042": 21061032,
            "1467104280": 37073168,
            "1467105518": 56226824,
            "1467106756": 0,
            "1467107994": 61999544,
            "1467109232": 0,
            "1467110470": 0,
            "1467111708": 26790872,
            "1467112946": 29429144,
            "1467114184": 85163296,
            "1467115422": 0,
            "1467117898": 28196368,
            "1467119136": 0,
            "1467120374": 46199384,
            "1467121612": 83895888,
            "1467124088": 19672208,
            "1467125326": 84634040,
            "1467126564": 93244928,
            "1467129040": 5242248,
            "1467130278": 84587584,
            "1467131516": 0,
            "1467132754": 78679480,
            "1467135230": 19779312,
            "1467136468": 65770072,
            "1467138944": 2969624,
            "1467140182": 9410496,
            "1467141420": 5006496,
            "1467143896": 43782360,
            "1467146372": 0,
            "1467147610": 91490672,
            "1467148848": 13331008,
            "1467150086": 0,
            "1467151324": 60490624,
            "1467152562": 0,
            "1467153800": 0,
            "1467155038": 19772136,
            "1467156276": 0,
            "1467157514": 74968816,
            "1467158752": 89856672,
            "1467159990": 73784992,
            "1467161228": 0,
            "1467162466": 8892048,
            "1467164942": 85294624,
            "1467166180": 102953304,
            "1467167418": 90734512,
            "1467168656": 0,
            "1467169894": 5938256,
            "1467171132": 28965600,
            "1467172370": 26839288,
            "1467173608": 4386472,
            "1467174846": 69137752,
            "1467176084": 96880832,
            "1467177322": 77810424,
            "1467178560": 66080776,
            "1467182274": 16460024,
            "1467183512": 78225488,
            "1467184750": 0,
            "1467187226": 68038464,
            "1467188464": 0,
            "1467189702": 7160584,
            "1467190940": 0,
            "1467192178": 70475368,
            "1467194654": 2375312,
            "1467195892": 13846192,
            "1467198368": 62233504,
            "1467199606": 88877712,
            "1467200844": 0,
            "1467202082": 72632672,
            "1467203320": 108654808,
            "1467204558": 61242720,
            "1467205796": 0,
            "1467207034": 0,
            "1467208272": 18418000,
            "1467209510": 87725608,
            "1467210748": 78836944,
            "1467211986": 0,
            "1467213224": 0,
            "1467215700": 1117832,
            "1467216938": 73283768,
            "1467218176": 0,
            "1467219414": 80848960,
            "1467220652": 0,
            "1467221890": 33970832,
            "1467223128": 23287944,
            "1467224366": 0,
            "1467225604": 23585168,
            "1467226842": 0,
            "1467228080": 28487128,
            "1467229318": 4977736,
            "1467230556": 90171064,
            "1467233032": 27683016,
            "1467234270": 77534464,
            "1467235508": 85958008,
            "1467236746": 0,
            "1467237984": 0,
            "1467239222": 0,
            "1467240460": 73044880,
            "1467241698": 91222816,
            "1467242936": 74177608,
            "1467244174": 43850312,
            "1467245412": 0,
            "1467246650": 33914504,
            "1467247888": 0,
            "1467249126": 0,
            "1467251602": 80564680,
            "1467252840": 96260840,
            "1467254078": 116959008,
            "1467255316": 64164432,
            "1467256554": 6485688,
            "1467259030": 17960064,
            "1467260268": 26443576,
            "1467261506": 94495904,
            "1467262744": 0,
            "1467265220": 108246872,
            "1467267696": 0,
            "1467268934": 42579240,
            "1467270172": 82041496,
            "1467272648": 0,
            "1467273886": 26091632,
            "1467275124": 0,
            "1467276362": 66722544,
            "1467277600": 102038904,
            "1467278838": 85439928,
            "1467280076": 68357456,
            "1467281314": 120435760,
            "1467283790": 0,
            "1467285028": 56439352,
            "1467286266": 80184016,
            "1467288742": 30790496,
            "1467291218": 81895720,
            "1467292456": 78105344,
            "1467293694": 109212160,
            "1467296170": 0,
            "1467297408": 114766912,
            "1467298646": 105400656,
            "1467301122": 0,
            "1467302360": 0,
            "1467303598": 63503480,
            "1467304836": 93109752,
            "1467307312": 0,
            "1467309788": 39355128,
            "1467311026": 16244976,
            "1467312264": 0,
            "1467313502": 66977688,
            "1467314740": 96243760,
            "1467315978": 79732280,
            "1467319692": 0,
            "1467320930": 0,
            "1467322168": 0,
            "1467323406": 0,
            "1467324644": 0,
            "1467325882": 0,
            "1467327120": 0,
            "1467328358": 0,
            "1467329596": 0,
            "1467330834": 0,
            "1467332072": 0,
            "1467333310": 0,
            "1467334548": 0,
            "1467335786": 0,
            "1467337024": 0,
            "1467338262": 0,
            "1467339500": 0,
            "1467340738": 0,
            "1467341976": 0,
            "1467343214": 0,
            "1467344452": 0,
            "1467345690": 0,
            "1467346928": 0,
            "1467348166": 0,
            "1467349404": 0,
            "1467350642": 0,
            "1467351880": 0,
            "1467353118": 0,
            "1467354356": 0,
            "1467355594": 0,
            "1467356832": 0,
            "1467358070": 0,
            "1467359308": 0,
            "1467360546": 0,
            "1467361784": 0,
            "1467363022": 0,
            "1467364260": 0,
            "1467365498": 0,
            "1467366736": 0,
            "1467367974": 0,
            "1467369212": 0,
            "1467370450": 0,
            "1467371688": 0,
            "1467372926": 0,
            "1467374164": 0,
            "1467375402": 0,
            "1467376640": 0,
            "1467377878": 0,
            "1467379116": 0,
            "1467380354": 0,
            "1467381592": 0,
            "1467382830": 0,
            "1467384068": 0,
            "1467385306": 0,
            "1467386544": 0,
            "1467387782": 0,
            "1467389020": 0,
            "1467390258": 0
          }
        },
        {
          "data_source_identifier": "218.234.174.22",
          "data_source_parent": "Rowe LLC",
          "data_type": "SSL",
          "in": {
            "1467080758": 0,
            "1467081996": 0,
            "1467083234": 0,
            "1467084472": 0,
            "1467085710": 0,
            "1467086948": 0,
            "1467088186": 0,
            "1467089424": 0,
            "1467090662": 0,
            "1467091900": 0,
            "1467093138": 0,
            "1467094376": 0,
            "1467095614": 0,
            "1467096852": 0,
            "1467098090": 0,
            "1467099328": 0,
            "1467100566": 0,
            "1467101804": 241497856,
            "1467103042": 238027520,
            "1467104280": 0,
            "1467105518": 954729928,
            "1467106756": 794414800,
            "1467107994": 875005320,
            "1467109232": 865233216,
            "1467110470": 0,
            "1467111708": 0,
            "1467112946": 151266624,
            "1467114184": 24491184,
            "1467115422": 552629720,
            "1467117898": 0,
            "1467119136": 554519288,
            "1467120374": 644687696,
            "1467121612": 535262648,
            "1467124088": 8266816,
            "1467125326": 875103392,
            "1467126564": 0,
            "1467129040": 317138456,
            "1467130278": 862225208,
            "1467131516": 912205512,
            "1467132754": 0,
            "1467135230": 0,
            "1467136468": 715514632,
            "1467138944": 0,
            "1467140182": 1633792,
            "1467141420": 209544328,
            "1467143896": 384091240,
            "1467146372": 488261120,
            "1467147610": 0,
            "1467148848": 441910432,
            "1467150086": 843532920,
            "1467151324": 0,
            "1467152562": 910990504,
            "1467153800": 897000928,
            "1467155038": 0,
            "1467156276": 393010928,
            "1467157514": 889528304,
            "1467158752": 0,
            "1467159990": 0,
            "1467161228": 661604080,
            "1467162466": 0,
            "1467164942": 487196568,
            "1467166180": 138329160,
            "1467167418": 0,
            "1467168656": 751713000,
            "1467169894": 945302280,
            "1467171132": 657959136,
            "1467172370": 744025872,
            "1467173608": 0,
            "1467174846": 516615376,
            "1467176084": 0,
            "1467177322": 496411296,
            "1467178560": 854530032,
            "1467182274": 741389696,
            "1467183512": 0,
            "1467184750": 365575632,
            "1467187226": 76781936,
            "1467188464": 479329088,
            "1467189702": 921174272,
            "1467190940": 811543176,
            "1467192178": 626420896,
            "1467194654": 357743344,
            "1467195892": 0,
            "1467198368": 279658312,
            "1467199606": 0,
            "1467200844": 247948496,
            "1467202082": 713357184,
            "1467203320": 870829888,
            "1467204558": 0,
            "1467205796": 5569048,
            "1467207034": 0,
            "1467208272": 72400600,
            "1467209510": 45927544,
            "1467210748": 30932992,
            "1467211986": 158675552,
            "1467213224": 393533904,
            "1467215700": 0,
            "1467216938": 637265192,
            "1467218176": 754524808,
            "1467219414": 813787976,
            "1467220652": 567888528,
            "1467221890": 0,
            "1467223128": 942237544,
            "1467224366": 976443536,
            "1467225604": 0,
            "1467226842": 0,
            "1467228080": 262707640,
            "1467229318": 0,
            "1467230556": 0,
            "1467233032": 808759408,
            "1467234270": 959167688,
            "1467235508": 0,
            "1467236746": 0,
            "1467237984": 136756576,
            "1467239222": 923578640,
            "1467240460": 911812616,
            "1467241698": 0,
            "1467242936": 91416816,
            "1467244174": 0,
            "1467245412": 73593648,
            "1467246650": 246030680,
            "1467247888": 51180464,
            "1467249126": 768933728,
            "1467251602": 0,
            "1467252840": 606103568,
            "1467254078": 0,
            "1467255316": 411153424,
            "1467256554": 277204928,
            "1467259030": 728589144,
            "1467260268": 0,
            "1467261506": 137265712,
            "1467262744": 809327560,
            "1467265220": 0,
            "1467267696": 17492920,
            "1467268934": 827414064,
            "1467270172": 0,
            "1467272648": 338329864,
            "1467273886": 898290176,
            "1467275124": 917279656,
            "1467276362": 0,
            "1467277600": 0,
            "1467278838": 871703088,
            "1467280076": 710188952,
            "1467281314": 0,
            "1467283790": 664007448,
            "1467285028": 804198240,
            "1467286266": 0,
            "1467288742": 53393744,
            "1467291218": 737036000,
            "1467292456": 80661032,
            "1467293694": 0,
            "1467296170": 742478208,
            "1467297408": 777910336,
            "1467298646": 444120600,
            "1467301122": 926272536,
            "1467302360": 1011730232,
            "1467303598": 573550096,
            "1467304836": 0,
            "1467307312": 831698528,
            "1467309788": 0,
            "1467311026": 0,
            "1467312264": 35359936,
            "1467313502": 534446672,
            "1467314740": 0,
            "1467315978": 520835832,
            "1467319692": 0,
            "1467320930": 0,
            "1467322168": 0,
            "1467323406": 0,
            "1467324644": 0,
            "1467325882": 0,
            "1467327120": 0,
            "1467328358": 0,
            "1467329596": 0,
            "1467330834": 0,
            "1467332072": 0,
            "1467333310": 0,
            "1467334548": 0,
            "1467335786": 0,
            "1467337024": 0,
            "1467338262": 0,
            "1467339500": 0,
            "1467340738": 0,
            "1467341976": 0,
            "1467343214": 0,
            "1467344452": 0,
            "1467345690": 0,
            "1467346928": 0,
            "1467348166": 0,
            "1467349404": 0,
            "1467350642": 0,
            "1467351880": 0,
            "1467353118": 0,
            "1467354356": 0,
            "1467355594": 0,
            "1467356832": 0,
            "1467358070": 0,
            "1467359308": 0,
            "1467360546": 0,
            "1467361784": 0,
            "1467363022": 0,
            "1467364260": 0,
            "1467365498": 0,
            "1467366736": 0,
            "1467367974": 0,
            "1467369212": 0,
            "1467370450": 0,
            "1467371688": 0,
            "1467372926": 0,
            "1467374164": 0,
            "1467375402": 0,
            "1467376640": 0,
            "1467377878": 0,
            "1467379116": 0,
            "1467380354": 0,
            "1467381592": 0,
            "1467382830": 0,
            "1467384068": 0,
            "1467385306": 0,
            "1467386544": 0,
            "1467387782": 0,
            "1467389020": 0,
            "1467390258": 0
          },
          "out": {
            "1467080758": 0,
            "1467081996": 0,
            "1467083234": 0,
            "1467084472": 0,
            "1467085710": 0,
            "1467086948": 0,
            "1467088186": 0,
            "1467089424": 0,
            "1467090662": 0,
            "1467091900": 0,
            "1467093138": 0,
            "1467094376": 0,
            "1467095614": 0,
            "1467096852": 0,
            "1467098090": 0,
            "1467099328": 0,
            "1467100566": 0,
            "1467101804": 31826464,
            "1467103042": 21794824,
            "1467104280": 0,
            "1467105518": 79911632,
            "1467106756": 65303888,
            "1467107994": 92015568,
            "1467109232": 99799696,
            "1467110470": 0,
            "1467111708": 0,
            "1467112946": 31622696,
            "1467114184": 0,
            "1467115422": 62625688,
            "1467117898": 0,
            "1467119136": 69246664,
            "1467120374": 86943576,
            "1467121612": 56117368,
            "1467124088": 8430776,
            "1467125326": 84747712,
            "1467126564": 0,
            "1467129040": 36480632,
            "1467130278": 77877496,
            "1467131516": 74126696,
            "1467132754": 0,
            "1467135230": 0,
            "1467136468": 69078816,
            "1467138944": 0,
            "1467140182": 5218968,
            "1467141420": 20327760,
            "1467143896": 35429664,
            "1467146372": 42652160,
            "1467147610": 0,
            "1467148848": 49718032,
            "1467150086": 90606272,
            "1467151324": 0,
            "1467152562": 100804544,
            "1467153800": 87413496,
            "1467155038": 0,
            "1467156276": 23493928,
            "1467157514": 60484176,
            "1467158752": 317480,
            "1467159990": 0,
            "1467161228": 40529392,
            "1467162466": 10359568,
            "1467164942": 55929096,
            "1467166180": 17257856,
            "1467167418": 0,
            "1467168656": 92946400,
            "1467169894": 83674176,
            "1467171132": 58613688,
            "1467172370": 80019712,
            "1467173608": 0,
            "1467174846": 39068048,
            "1467176084": 0,
            "1467177322": 44167472,
            "1467178560": 85493272,
            "1467182274": 74313848,
            "1467183512": 0,
            "1467184750": 26876928,
            "1467187226": 15515744,
            "1467188464": 47704832,
            "1467189702": 78234096,
            "1467190940": 87350648,
            "1467192178": 74592368,
            "1467194654": 48197008,
            "1467195892": 0,
            "1467198368": 45893448,
            "1467199606": 0,
            "1467200844": 38539784,
            "1467202082": 82040760,
            "1467203320": 97426848,
            "1467204558": 0,
            "1467205796": 0,
            "1467207034": 0,
            "1467208272": 15427936,
            "1467209510": 24524416,
            "1467210748": 13229144,
            "1467211986": 0,
            "1467213224": 37926848,
            "1467215700": 0,
            "1467216938": 76580480,
            "1467218176": 72352496,
            "1467219414": 91127296,
            "1467220652": 53883936,
            "1467221890": 0,
            "1467223128": 90196272,
            "1467224366": 86683880,
            "1467225604": 0,
            "1467226842": 5169304,
            "1467228080": 16213712,
            "1467229318": 9663464,
            "1467230556": 0,
            "1467233032": 65308160,
            "1467234270": 96469432,
            "1467235508": 0,
            "1467236746": 3273648,
            "1467237984": 4758136,
            "1467239222": 84232024,
            "1467240460": 87098360,
            "1467241698": 0,
            "1467242936": 157320,
            "1467244174": 14256680,
            "1467245412": 4490592,
            "1467246650": 17846656,
            "1467247888": 0,
            "1467249126": 70157680,
            "1467251602": 0,
            "1467252840": 67316888,
            "1467254078": 0,
            "1467255316": 54744096,
            "1467256554": 23767120,
            "1467259030": 70607368,
            "1467260268": 0,
            "1467261506": 21301864,
            "1467262744": 66224416,
            "1467265220": 0,
            "1467267696": 42544816,
            "1467268934": 75615304,
            "1467270172": 0,
            "1467272648": 2739480,
            "1467273886": 80519424,
            "1467275124": 84592232,
            "1467276362": 0,
            "1467277600": 0,
            "1467278838": 89690992,
            "1467280076": 80328128,
            "1467281314": 0,
            "1467283790": 96126096,
            "1467285028": 84160928,
            "1467286266": 0,
            "1467288742": 5069208,
            "1467291218": 77109912,
            "1467292456": 0,
            "1467293694": 0,
            "1467296170": 82970552,
            "1467297408": 81700800,
            "1467298646": 39722672,
            "1467301122": 79082352,
            "1467302360": 102078952,
            "1467303598": 78483144,
            "1467304836": 0,
            "1467307312": 101075704,
            "1467309788": 0,
            "1467311026": 9440736,
            "1467312264": 4604032,
            "1467313502": 72199016,
            "1467314740": 0,
            "1467315978": 46107856,
            "1467319692": 0,
            "1467320930": 0,
            "1467322168": 0,
            "1467323406": 0,
            "1467324644": 0,
            "1467325882": 0,
            "1467327120": 0,
            "1467328358": 0,
            "1467329596": 0,
            "1467330834": 0,
            "1467332072": 0,
            "1467333310": 0,
            "1467334548": 0,
            "1467335786": 0,
            "1467337024": 0,
            "1467338262": 0,
            "1467339500": 0,
            "1467340738": 0,
            "1467341976": 0,
            "1467343214": 0,
            "1467344452": 0,
            "1467345690": 0,
            "1467346928": 0,
            "1467348166": 0,
            "1467349404": 0,
            "1467350642": 0,
            "1467351880": 0,
            "1467353118": 0,
            "1467354356": 0,
            "1467355594": 0,
            "1467356832": 0,
            "1467358070": 0,
            "1467359308": 0,
            "1467360546": 0,
            "1467361784": 0,
            "1467363022": 0,
            "1467364260": 0,
            "1467365498": 0,
            "1467366736": 0,
            "1467367974": 0,
            "1467369212": 0,
            "1467370450": 0,
            "1467371688": 0,
            "1467372926": 0,
            "1467374164": 0,
            "1467375402": 0,
            "1467376640": 0,
            "1467377878": 0,
            "1467379116": 0,
            "1467380354": 0,
            "1467381592": 0,
            "1467382830": 0,
            "1467384068": 0,
            "1467385306": 0,
            "1467386544": 0,
            "1467387782": 0,
            "1467389020": 0,
            "1467390258": 0
          }
        }
      ],
      "totals": {
        "in": {
          "1467080758": 0,
          "1467081996": 0,
          "1467083234": 0,
          "1467084472": 0,
          "1467085710": 0,
          "1467086948": 0,
          "1467088186": 0,
          "1467089424": 0,
          "1467090662": 0,
          "1467091900": 0,
          "1467093138": 0,
          "1467094376": 0,
          "1467095614": 0,
          "1467096852": 0,
          "1467098090": 0,
          "1467099328": 0,
          "1467100566": 0,
          "1467101804": 458636144,
          "1467103042": 383335896,
          "1467104280": 307148776,
          "1467105518": 1499238304,
          "1467106756": 794414800,
          "1467107994": 1295437880,
          "1467109232": 865233216,
          "1467110470": 109454664,
          "1467111708": 182808536,
          "1467112946": 309693096,
          "1467114184": 844339248,
          "1467115422": 552629720,
          "1467117898": 301536480,
          "1467119136": 554519288,
          "1467120374": 1367019192,
          "1467121612": 1363239872,
          "1467124088": 118674656,
          "1467125326": 1637389280,
          "1467126564": 861812776,
          "1467129040": 602381064,
          "1467130278": 1773666864,
          "1467131516": 912205512,
          "1467132754": 660007232,
          "1467135230": 138487544,
          "1467136468": 1261265512,
          "1467138944": 0,
          "1467140182": 34189144,
          "1467141420": 209544328,
          "1467143896": 784191304,
          "1467146372": 488261120,
          "1467147610": 821975776,
          "1467148848": 593257912,
          "1467150086": 843532920,
          "1467151324": 572727688,
          "1467152562": 910990504,
          "1467153800": 897000928,
          "1467155038": 228804672,
          "1467156276": 393010928,
          "1467157514": 1696720736,
          "1467158752": 996707992,
          "1467159990": 777985992,
          "1467161228": 661604080,
          "1467162466": 295126192,
          "1467164942": 1368391312,
          "1467166180": 1081150032,
          "1467167418": 880257936,
          "1467168656": 751713000,
          "1467169894": 945302280,
          "1467171132": 1054838128,
          "1467172370": 1023082672,
          "1467173608": 111492104,
          "1467174846": 1336328896,
          "1467176084": 975066904,
          "1467177322": 1477339200,
          "1467178560": 1474394272,
          "1467182274": 1086366240,
          "1467183512": 920085688,
          "1467184750": 365575632,
          "1467187226": 741395520,
          "1467188464": 479329088,
          "1467189702": 954747080,
          "1467190940": 811543176,
          "1467192178": 1268194744,
          "1467194654": 599412424,
          "1467195892": 126998536,
          "1467198368": 1063952144,
          "1467199606": 966677656,
          "1467200844": 247948496,
          "1467202082": 1391003224,
          "1467203320": 1883036616,
          "1467204558": 439831432,
          "1467205796": 5569048,
          "1467207034": 49039992,
          "1467208272": 267631864,
          "1467209510": 919251104,
          "1467210748": 887848624,
          "1467211986": 158675552,
          "1467213224": 393533904,
          "1467215700": 79292928,
          "1467216938": 1350923248,
          "1467218176": 754524808,
          "1467219414": 1499525896,
          "1467220652": 567888528,
          "1467221890": 0,
          "1467223128": 1302503496,
          "1467224366": 976443536,
          "1467225604": 434273728,
          "1467226842": 0,
          "1467228080": 479032144,
          "1467229318": 0,
          "1467230556": 851006360,
          "1467233032": 1143477648,
          "1467234270": 1813522856,
          "1467235508": 779245856,
          "1467236746": 0,
          "1467237984": 136756576,
          "1467239222": 923578640,
          "1467240460": 1454472920,
          "1467241698": 782791880,
          "1467242936": 854539712,
          "1467244174": 408041888,
          "1467245412": 73593648,
          "1467246650": 609492168,
          "1467247888": 51180464,
          "1467249126": 768933728,
          "1467251602": 702242904,
          "1467252840": 1271685392,
          "1467254078": 912337056,
          "1467255316": 1018259872,
          "1467256554": 489978576,
          "1467259030": 982436232,
          "1467260268": 272247312,
          "1467261506": 1026724104,
          "1467262744": 809327560,
          "1467265220": 984081728,
          "1467267696": 17492920,
          "1467268934": 1408382656,
          "1467270172": 891309648,
          "1467272648": 338329864,
          "1467273886": 1145542144,
          "1467275124": 917279656,
          "1467276362": 676973864,
          "1467277600": 1005099440,
          "1467278838": 1800064848,
          "1467280076": 1337677368,
          "1467281314": 1011717416,
          "1467283790": 664007448,
          "1467285028": 1329070016,
          "1467286266": 663324224,
          "1467288742": 395760624,
          "1467291218": 1614880064,
          "1467292456": 743981896,
          "1467293694": 884311608,
          "1467296170": 742478208,
          "1467297408": 1819029552,
          "1467298646": 1341993992,
          "1467301122": 926272536,
          "1467302360": 1011730232,
          "1467303598": 1375428592,
          "1467304836": 903899368,
          "1467307312": 831698528,
          "1467309788": 256131072,
          "1467311026": 225189000,
          "1467312264": 127851896,
          "1467313502": 1309174024,
          "1467314740": 975401880,
          "1467315978": 1406026816,
          "1467319692": 0,
          "1467320930": 0,
          "1467322168": 0,
          "1467323406": 0,
          "1467324644": 0,
          "1467325882": 0,
          "1467327120": 0,
          "1467328358": 0,
          "1467329596": 0,
          "1467330834": 0,
          "1467332072": 0,
          "1467333310": 0,
          "1467334548": 0,
          "1467335786": 0,
          "1467337024": 0,
          "1467338262": 0,
          "1467339500": 0,
          "1467340738": 0,
          "1467341976": 0,
          "1467343214": 0,
          "1467344452": 0,
          "1467345690": 0,
          "1467346928": 0,
          "1467348166": 0,
          "1467349404": 0,
          "1467350642": 0,
          "1467351880": 0,
          "1467353118": 0,
          "1467354356": 0,
          "1467355594": 0,
          "1467356832": 0,
          "1467358070": 0,
          "1467359308": 0,
          "1467360546": 0,
          "1467361784": 0,
          "1467363022": 0,
          "1467364260": 0,
          "1467365498": 0,
          "1467366736": 0,
          "1467367974": 0,
          "1467369212": 0,
          "1467370450": 0,
          "1467371688": 0,
          "1467372926": 0,
          "1467374164": 0,
          "1467375402": 0,
          "1467376640": 0,
          "1467377878": 0,
          "1467379116": 0,
          "1467380354": 0,
          "1467381592": 0,
          "1467382830": 0,
          "1467384068": 0,
          "1467385306": 0,
          "1467386544": 0,
          "1467387782": 0,
          "1467389020": 0,
          "1467390258": 0
        },
        "out": {
          "1467080758": 0,
          "1467081996": 0,
          "1467083234": 0,
          "1467084472": 0,
          "1467085710": 0,
          "1467086948": 0,
          "1467088186": 0,
          "1467089424": 0,
          "1467090662": 0,
          "1467091900": 0,
          "1467093138": 0,
          "1467094376": 0,
          "1467095614": 0,
          "1467096852": 0,
          "1467098090": 0,
          "1467099328": 0,
          "1467100566": 0,
          "1467101804": 55286320,
          "1467103042": 42855856,
          "1467104280": 37073168,
          "1467105518": 136138456,
          "1467106756": 65303888,
          "1467107994": 154015112,
          "1467109232": 99799696,
          "1467110470": 0,
          "1467111708": 26790872,
          "1467112946": 61051840,
          "1467114184": 85163296,
          "1467115422": 62625688,
          "1467117898": 28196368,
          "1467119136": 69246664,
          "1467120374": 133142960,
          "1467121612": 140013256,
          "1467124088": 28102984,
          "1467125326": 169381752,
          "1467126564": 93244928,
          "1467129040": 41722880,
          "1467130278": 162465080,
          "1467131516": 74126696,
          "1467132754": 78679480,
          "1467135230": 19779312,
          "1467136468": 134848888,
          "1467138944": 2969624,
          "1467140182": 14629464,
          "1467141420": 25334256,
          "1467143896": 79212024,
          "1467146372": 42652160,
          "1467147610": 91490672,
          "1467148848": 63049040,
          "1467150086": 90606272,
          "1467151324": 60490624,
          "1467152562": 100804544,
          "1467153800": 87413496,
          "1467155038": 19772136,
          "1467156276": 23493928,
          "1467157514": 135452992,
          "1467158752": 90174152,
          "1467159990": 73784992,
          "1467161228": 40529392,
          "1467162466": 19251616,
          "1467164942": 141223720,
          "1467166180": 120211160,
          "1467167418": 90734512,
          "1467168656": 92946400,
          "1467169894": 89612432,
          "1467171132": 87579288,
          "1467172370": 106859000,
          "1467173608": 4386472,
          "1467174846": 108205800,
          "1467176084": 96880832,
          "1467177322": 121977896,
          "1467178560": 151574048,
          "1467182274": 90773872,
          "1467183512": 78225488,
          "1467184750": 26876928,
          "1467187226": 83554208,
          "1467188464": 47704832,
          "1467189702": 85394680,
          "1467190940": 87350648,
          "1467192178": 145067736,
          "1467194654": 50572320,
          "1467195892": 13846192,
          "1467198368": 108126952,
          "1467199606": 88877712,
          "1467200844": 38539784,
          "1467202082": 154673432,
          "1467203320": 206081656,
          "1467204558": 61242720,
          "1467205796": 0,
          "1467207034": 0,
          "1467208272": 33845936,
          "1467209510": 112250024,
          "1467210748": 92066088,
          "1467211986": 0,
          "1467213224": 37926848,
          "1467215700": 1117832,
          "1467216938": 149864248,
          "1467218176": 72352496,
          "1467219414": 171976256,
          "1467220652": 53883936,
          "1467221890": 33970832,
          "1467223128": 113484216,
          "1467224366": 86683880,
          "1467225604": 23585168,
          "1467226842": 5169304,
          "1467228080": 44700840,
          "1467229318": 14641200,
          "1467230556": 90171064,
          "1467233032": 92991176,
          "1467234270": 174003896,
          "1467235508": 85958008,
          "1467236746": 3273648,
          "1467237984": 4758136,
          "1467239222": 84232024,
          "1467240460": 160143240,
          "1467241698": 91222816,
          "1467242936": 74334928,
          "1467244174": 58106992,
          "1467245412": 4490592,
          "1467246650": 51761160,
          "1467247888": 0,
          "1467249126": 70157680,
          "1467251602": 80564680,
          "1467252840": 163577728,
          "1467254078": 116959008,
          "1467255316": 118908528,
          "1467256554": 30252808,
          "1467259030": 88567432,
          "1467260268": 26443576,
          "1467261506": 115797768,
          "1467262744": 66224416,
          "1467265220": 108246872,
          "1467267696": 42544816,
          "1467268934": 118194544,
          "1467270172": 82041496,
          "1467272648": 2739480,
          "1467273886": 106611056,
          "1467275124": 84592232,
          "1467276362": 66722544,
          "1467277600": 102038904,
          "1467278838": 175130920,
          "1467280076": 148685584,
          "1467281314": 120435760,
          "1467283790": 96126096,
          "1467285028": 140600280,
          "1467286266": 80184016,
          "1467288742": 35859704,
          "1467291218": 159005632,
          "1467292456": 78105344,
          "1467293694": 109212160,
          "1467296170": 82970552,
          "1467297408": 196467712,
          "1467298646": 145123328,
          "1467301122": 79082352,
          "1467302360": 102078952,
          "1467303598": 141986624,
          "1467304836": 93109752,
          "1467307312": 101075704,
          "1467309788": 39355128,
          "1467311026": 25685712,
          "1467312264": 4604032,
          "1467313502": 139176704,
          "1467314740": 96243760,
          "1467315978": 125840136,
          "1467319692": 0,
          "1467320930": 0,
          "1467322168": 0,
          "1467323406": 0,
          "1467324644": 0,
          "1467325882": 0,
          "1467327120": 0,
          "1467328358": 0,
          "1467329596": 0,
          "1467330834": 0,
          "1467332072": 0,
          "1467333310": 0,
          "1467334548": 0,
          "1467335786": 0,
          "1467337024": 0,
          "1467338262": 0,
          "1467339500": 0,
          "1467340738": 0,
          "1467341976": 0,
          "1467343214": 0,
          "1467344452": 0,
          "1467345690": 0,
          "1467346928": 0,
          "1467348166": 0,
          "1467349404": 0,
          "1467350642": 0,
          "1467351880": 0,
          "1467353118": 0,
          "1467354356": 0,
          "1467355594": 0,
          "1467356832": 0,
          "1467358070": 0,
          "1467359308": 0,
          "1467360546": 0,
          "1467361784": 0,
          "1467363022": 0,
          "1467364260": 0,
          "1467365498": 0,
          "1467366736": 0,
          "1467367974": 0,
          "1467369212": 0,
          "1467370450": 0,
          "1467371688": 0,
          "1467372926": 0,
          "1467374164": 0,
          "1467375402": 0,
          "1467376640": 0,
          "1467377878": 0,
          "1467379116": 0,
          "1467380354": 0,
          "1467381592": 0,
          "1467382830": 0,
          "1467384068": 0,
          "1467385306": 0,
          "1467386544": 0,
          "1467387782": 0,
          "1467389020": 0,
          "1467390258": 0
        }
      }
    },
    "totals": [
      {
        "data_source_identifier": "145.214.83.54",
        "data_source_parent": "Anderson-Vandervort",
        "data_type": "Call of Duty",
        "totals": {
          "total_in": 855408253,
          "total_out": 89574386,
          "combined_total": 944982639
        }
      },
      {
        "data_source_identifier": "218.234.174.22",
        "data_source_parent": "Rowe LLC",
        "data_type": "SSL",
        "totals": {
          "total_in": 861366560,
          "total_out": 88558681,
          "combined_total": 949925241
        }
      }
    ]
  }
}

Account_Data_Usage - Update current aggregated data usage for an account

Modify the current billing period data usage. This can only be performed on the most recent, unclosed data usage history. You should not use this to add real, current usage to an account, instead use the Add granular data usage to an account endpoint. This is only to correct mistakes in billable/free usage. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:id/data_usage_histories

Parameter

Field	Type	Description
id	Number	The ID of the account
billable_in_bytes	Number	The number of billable inbound bytes used in the current period.
billable_out_bytes	Number	The number of billable outbound bytes used in the current period.
free_in_bytes	Number	The number of free inbound bytes used in the current period.
free_out_bytes	Number	The number of free outbound bytes used in the current period.

Success 200

Field	Type	Description
id	Number	The ID of the data usage history
billable_in_bytes	Number	The number of billable inbound bytes used in the current period.
billable_out_bytes	Number	The number of billable outbound bytes used in the current period.
free_in_bytes	Number	The number of free inbound bytes used in the current period.
free_out_bytes	Number	The number of free outbound bytes used in the current period.
start_time	DateTime	When the data began to be aggregated (UTC)
closed_time	DateTime	When the data aggregation was stopped for this item (UTC.) Will always be null from this endpoint.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 136,
    "billable_in_bytes": 0,
    "billable_out_bytes": 0,
    "free_in_bytes": 0,
    "free_out_bytes": 0,
    "start_time": "2016-06-25 00:51:18",
    "closed_time": null
  }
}

Account IP Addresses

Account_IP_Addresses - Assign an IP to an account

This endpoint allows you to assign IPv4/IPv6 assignments to an account, a RADIUS account on an account, an uninventoried MAC address, or an inventory model field on an account. Please see the documentation for more details about the different scenarios in which you would pick each entity.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field	Type	Description
id	Number	The ID of the account
subnet	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32. If this is in a pool, and is assigned to a RADIUS account, it will be written as a Framed-IP-Address. Otherwise, it will be written as a Framed-Route.
assigned_entity	String	The entity to assign this to - the account directly, a RADIUS account on the account, an inventory item on the account, or a non-inventoried MAC address. You should only use the non-inventoried MAC address option to add an assignment to a device you do not own (e.g. a customer router.) Allowed values: `"accounts"`, `"inventory_items"`, `"radius_accounts"`, `"non_inventoried_mac_addresses"`
assigned_id optional	Number	The ID of the entity referenced in assigned_entity. If assigned_entity is 'accounts' or 'non_inventoried_mac_addresses', this can be omitted.
inventory_item_field_id optional	Number	If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.) This is required if assigned_entity is "inventory_items"
non_inventoried_mac_address optional	String	If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.
description optional	String	Optional description for the assignment
service_id optional	Number	If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service that the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
       "id": 8,
       "subnet_id": 1,
       "subnet": "192.168.100.17/32",
       "assigned_entity": "accounts",
       "assigned_id": 1,
       "inventory_item_field_id": null,
       "ip_pool_id": null,
       "account_id": 1,
       "service_id": 4,
       "non_inventoried_mac_address": null,
       "description": null,
       "soft": false
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Account_IP_Addresses - Assign an IP to an account

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field	Type	Description
id	Number	The ID of the account
subnet	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32. If this is in a pool, and is assigned to a RADIUS account, it will be written as a Framed-IP-Address. Otherwise, it will be written as a Framed-Route.
assigned_entity	String	The entity to assign this to - the account directly, a RADIUS account on the account, an inventory item on the account, or a non-inventoried MAC address. You should only use the non-inventoried MAC address option to add an assignment to a device you do not own (e.g. a customer router.) Allowed values: `"accounts"`, `"inventory_items"`, `"radius_accounts"`, `"non_inventoried_mac_addresses"`
assigned_id optional	Number	The ID of the entity referenced in assigned_entity. If assigned_entity is 'accounts' or 'non_inventoried_mac_addresses', this can be omitted.
inventory_item_field_id optional	Number	If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning) if you'd like to bind the IP directly to an interface. If you don't supply this when assigned_entity is `inventory_items`, then the IP will be attached directly to the inventory item.
non_inventoried_mac_address optional	String	If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.
description optional	String	Optional description for the assignment
service_id optional	Number	If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service that the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
       "id": 8,
       "subnet_id": 1,
       "subnet": "192.168.100.17/32",
       "assigned_entity": "accounts",
       "assigned_id": 1,
       "inventory_item_field_id": null,
       "ip_pool_id": null,
       "account_id": 1,
       "service_id": 4,
       "non_inventoried_mac_address": null,
       "description": null,
       "soft": false
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Account_IP_Addresses - Assign an IP to an account

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field	Type	Description
id	Number	The ID of the account
subnet	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32. If this is in a pool, and is assigned to a RADIUS account, it will be written as a Framed-IP-Address. Otherwise, it will be written as a Framed-Route.
assigned_entity	String	The entity to assign this to - the account directly, a RADIUS account on the account, an inventory item on the account, or a non-inventoried MAC address. You should only use the non-inventoried MAC address option to add an assignment to a device you do not own (e.g. a customer router.) Allowed values: `"accounts"`, `"inventory_items"`, `"radius_accounts"`, `"non_inventoried_mac_addresses"`
assigned_id optional	Number	The ID of the entity referenced in assigned_entity. If assigned_entity is 'accounts' or 'non_inventoried_mac_addresses', this can be omitted.
inventory_item_field_id optional	Number	If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.) This is required if assigned_entity is "inventory_items"
non_inventoried_mac_address optional	String	If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.
description optional	String	Optional description for the assignment
service_id optional	Number	If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service that the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
       "id": 8,
       "subnet_id": 1,
       "subnet": "192.168.100.17/32",
       "assigned_entity": "accounts",
       "assigned_id": 1,
       "ip_pool_id": null,
       "account_id": 1,
       "service_id": 4,
       "non_inventoried_mac_address": null,
       "description": null
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Account_IP_Addresses - Delete IP assignment

Delete an IP assignment.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the account
ip_assignment_id	Number	The ID of the IP assignment

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the IP assignment could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "You cannot delete this subnet, as other subnets are using it as their next hop."
         },
         "status_code": 422
     }
 }

Account_IP_Addresses - Get all IP assignments

Retrieve a list of existing IP assignments on the account.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the account

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
         "id": 1,
         "subnet_id": 1,
         "subnet": "192.168.100.5",
         "assigned_entity": "accounts",
         "assigned_id": 1,
         "inventory_item_field_id": null,
         "ip_pool_id": null,
         "account_id": 1,
         "service_id": 4,
         "non_inventoried_mac_address": null,
         "description": null,
         "soft": false
       },
       {
         "id": 2,
         "subnet_id": 1,
         "subnet": "192.168.100.6",
         "assigned_entity": "accounts",
         "assigned_id": 1,
         "inventory_item_field_id": null,
         "ip_pool_id": null,
          "account_id": 1,
          "service_id": 4,
          "non_inventoried_mac_address": null,
          "description": null,
          "soft": false
       }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_IP_Addresses - Get all IP assignments

Retrieve a list of existing IP assignments on the account.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the account

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
         "id": 1,
         "subnet_id": 1,
         "subnet": "192.168.100.5",
         "assigned_entity": "accounts",
         "assigned_id": 1,
         "ip_pool_id": null,
         "account_id": 1,
         "service_id": 4,
         "non_inventoried_mac_address": null,
         "description": null
       },
       {
         "id": 2,
         "subnet_id": 1,
         "subnet": "192.168.100.6",
         "assigned_entity": "accounts",
         "assigned_id": 1,
         "ip_pool_id": null,
          "account_id": 1,
          "service_id": 4,
          "non_inventoried_mac_address": null,
          "description": null
       }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_IP_Addresses - Get individual IP assignment

Retrieve a specific IP assignment.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the account
ip_assignment_id	Number	The ID of the IP assignment.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "inventory_item_field_id": null,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 3,
     "non_inventoried_mac_address": null,
     "description": null,
     "soft": false
   }
}

Account_IP_Addresses - Get individual IP assignment

Retrieve a specific IP assignment.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the account
ip_assignment_id	Number	The ID of the IP assignment.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment

Success-Response:

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 3,
     "non_inventoried_mac_address": null,
     "description": null
   }
}

Account_IP_Addresses - Update IP assignment

Update an existing IP assignment. If the assignment is on an account, only the subnet can be changed. If it is on a RADIUS account, only the subnet can be changed. If it is on an inventory item, the assigned_id, the subnet and inventory_item_field_id can be changed. To change the entity on an assignment other than an inventory item, delete the existing assignment and create a new one.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the account
ip_assignment_id	Number	The ID of the IP assignment
subnet optional	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.
assigned_id optional	Number	Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If the inventory item is not assigned to the same account as the existing assignment, it will be rejected. If the IP is currently assigned to an `inventory_item_field_id` and you supply this value and not `inventory_item_field_id`, the IP will be moved from the field level to the item level.
inventory_item_field_id optional	Number	If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).
non_inventoried_mac_address optional	String	If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format. If this is omitted, an dthe IP is currently associated with an inventory item field, then the IP will be moved from an existing field down to the inventory item level.
description optional	String	An optional description for the assignment
service_id optional	Number	If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.
make_permanent	Boolean	If this is set to `true`, and the `soft` property of this IP assignment is currently `true`, then this will be changed to a permanent assignment.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "inventory_item_field_id": null,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 4,
     "non_inventoried_mac_address": null,
     "description": null,
     "soft": false
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Account_IP_Addresses - Update IP assignment

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the account
ip_assignment_id	Number	The ID of the IP assignment
subnet optional	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.
assigned_id optional	Number	Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If you supply this, you must also supply inventory_item_field_id or the query will be rejected. If the inventory item is not assigned to the same account as the existing assignment, it will also be rejected.
inventory_item_field_id optional	Number	If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).
non_inventoried_mac_address optional	String	If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.
description optional	String	An optional description for the assignment
service_id optional	Number	If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.
make_permanent	Boolean	If this is set to `true`, and the `soft` property of this IP assignment is currently `true`, then this will be changed to a permanent assignment.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "inventory_item_field_id": null,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 4,
     "non_inventoried_mac_address": null,
     "description": null,
     "soft": false
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Account_IP_Addresses - Update IP assignment

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the account
ip_assignment_id	Number	The ID of the IP assignment
subnet optional	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.
assigned_id optional	Number	Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If you supply this, you must also supply inventory_item_field_id or the query will be rejected. If the inventory item is not assigned to the same account as the existing assignment, it will also be rejected.
inventory_item_field_id optional	Number	If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).
non_inventoried_mac_address optional	String	If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.
description optional	String	An optional description for the assignment
service_id optional	Number	If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
account_id	Number	The ID of the account the IP is assigned to
service_id	Number	The ID of the service the IP is associated with
non_inventoried_mac_address	String	If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.
description	String	An optional description for the assignment

Success-Response:

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 4,
     "non_inventoried_mac_address": null,
     "description": null
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Account Inventory

Account_Inventory - Get all inventory items

Get a list of inventory on a specific account.

https://example.sonar.software/api/v1/accounts/:id/inventory_items

Parameter

Field	Type	Description
id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": [
    {
      "id": 1,
      "inventory_model_id": 1,
      "status": "lost",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:00:00:00:00:DD"
        },
        {
          "field_id": 2,
          "data": ""
        }
      ]
    },
    {
      "id": 2,
      "inventory_model_id": 1,
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:00:00:00:00:0B"
        }
      ]
    },
    {
      "id": 29,
      "inventory_model_id": 1,
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:DD:11:AA:BB:CC"
        },
        {
          "field_id": 2,
          "data": "1"
        }
      ]
    },
    {
      "id": 30,
      "inventory_model_id": 1,
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:00:00:0A:BC:12"
        },
        {
          "field_id": 2,
          "data": "12345"
        }
      ]
    }
  ],
  "paginator": {
    "total_count": 4,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Inventory - Get individual inventory item

Get a specific inventory item on an account.

https://example.sonar.software/api/v1/accounts/:id/inventory_items/:item_id

Parameter

Field	Type	Description
id	Number	The ID of the account
item_id	Number	The ID of the inventory item

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 1,
    "status": "lost",
    "purchase_price": 0,
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "00:00:00:00:00:DD"
      },
      {
        "field_id": 2,
        "data": ""
      }
    ]
  }
}

Account Invoices

Account_Invoices - Apply a deposit to an invoice

Apply a deposit to an invoice. This will only work if the invoice has a remaining_due greater than 0 and the deposit has an amount_remaining greater than 0.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/apply_deposit/:deposit_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice
deposit_id	Number	The ID of the deposit

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
void	Boolean	Whether or not the invoice has been voided.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Apply a deposit to an invoice

Apply a deposit to an invoice. This will only work if the invoice has a remaining_due greater than 0 and the deposit has an amount_remaining greater than 0.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/apply_deposit/:deposit_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice
deposit_id	Number	The ID of the deposit

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Apply a discount to an invoice

Apply a discount to an invoice. This will only work if the invoice has a remaining_due greater than 0 and the discount has an amount_remaining greater than 0.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/apply_discount/:discount_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice
discount_id	Number	The ID of the discount

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
void	Boolean	Whether or not the invoice has been voided.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Apply a discount to an invoice

Apply a discount to an invoice. This will only work if the invoice has a remaining_due greater than 0 and the discount has an amount_remaining greater than 0.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/apply_discount/:discount_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice
discount_id	Number	The ID of the discount

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field	Type	Description
account_id	Number	The ID of the account
debits	Array	An array of debit IDs. These debits must be currently uninvoiced.
due_date	Date	A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
void	Boolean	Whether or not the invoice has been voided.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field	Type	Description
account_id	Number	The ID of the account
debits	Array	An array of debit IDs. These debits must be currently uninvoiced.
due_date optional	Date	A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date
message optional	String	An optional message that will be printed on the invoice

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
message	String	The optional invoice message

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "message": null
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field	Type	Description
account_id	Number	The ID of the account
debits	Array	An array of debit IDs. These debits must be currently uninvoiced
due_date	Date	A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date
date optional	Date	The date the invoice is for. If this is ommitted, then the date will be set to today. Generally, you should omit this unless you have a reason to fix the invoice to a different date

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 202 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field	Type	Description
account_id	Number	The ID of the account
debits	Array	An array of debit IDs. These debits must be currently uninvoiced
due_date	Date	A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date
date optional	Date	The date the invoice is for. If this is ommitted, then the date will be set to today. Generally, you should omit this unless you have a reason to fix the invoice to a different date

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 202 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field	Type	Description
account_id	Number	The ID of the account
debits	Array	An array of debit IDs. These debits must be currently uninvoiced.
due_date	Date	A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 202 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Delete an invoice

Delete an invoice. Invoices can only be deleted in limited circumstances - they must be created manually (not an automatic, recurring invoice) and the invoice date must be after the last accounting period close date. Once an invoice is deleted, any credits applied, or debits included in the invoice, will be returned to the account.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
success	Boolean	True if the invoice was deleted successfully.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "You cannot delete an invoice generated by the automatic billing process. Only manually created invoices can be deleted.",
     "status_code": 422
   }
 }

Account_Invoices - Freeze invoice

Freeze an invoice. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/freeze

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
void	Boolean	Whether or not the invoice has been voided.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Freeze invoice

Freeze an invoice. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/freeze

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Get a base64 encoded invoice PDF

Get an invoice as a PDF, base64 encoded

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/pdf

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
invoice_id	Number	The ID of the invoice
account_id	Number	The ID of the account
base64	String	The base64 encoded invoice

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "invoice_id": 1,
    "account_id": 22,
    "base64": "JVBERi0xLjQK...."
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_Invoices - Get a base64 encoded statement PDF

Get an invoice as a PDF, base64 encoded

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/pdf

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
invoice_id	Number	The ID of the invoice
account_id	Number	The ID of the account
base64	String	The base64 encoded statement

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "invoice_id": 1,
    "account_id": 22,
    "base64": "JVBERi0xLjQK...."
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_Invoices - Get all account invoices

Get a list of the invoices for the account

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
void	Boolean	Whether or not the invoice has been voided.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Invoices - Get all account invoices

Get a list of the invoices for the account

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Invoices - Get individual account invoice credits

Get an individual account invoice credits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/credits

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
id	Number	The ID of the credit
amount	Number	The amount of the credit, in system currency
void	Boolean	This will be true if the credit was reversed, or if the payment that created the credit is refunded or reversed
deposit_id	Number	If this was created by a deposit (payment) then this will be the ID of the deposit
discount_id	Number	If this was created by a discount, then this will be the ID of the discount
date	Date	The date the credit was applied, in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 263,
      "amount": 60.50,
      "void": false,
      "deposit_id": 5,
      "discount_id": 0,
      "date": "2015-09-23 16:55:13"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Invoices - Get individual account invoice debits

Get an individual account invoice debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/debits

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
id	Number	An ID representing the individual debit
amount	Number	The amount of the debit in the system currency
invoice_id	Number	The invoice the debit is associated with, if it is associated with an invoice. Null otherwise
service_id	Number	The ID of the service that the debit is associated with
date	Date	The date and time the debit was created in UTC
reversed	Boolean	If this is true, the debit has been reversed
reversed_at	Date	If reversed is true, this is the date the debit was reversed
discount_id	Number	If reversed is true, this is the ID of the discount that was created to reverse the debit
number_of_months	Number	If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 361,
      "amount": 34.34,
      "invoice_id": 366,
      "service_id": 22,
      "date": "2015-09-25 16:07:57",
      "reversed": false,
      "reversed_at": null,
      "discount_id": null,
      "number_of_months": 1,
      "taxes": []
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Invoices - Get individual account invoice

Get an individual account invoice.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
void	Boolean	Whether or not the invoice has been voided.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Get individual account invoice

Get an individual account invoice.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Link a child invoice to a master

Link a child invoice to a master. This generally does not need to be done manually, and is performed automatically by regular billing. Don't use this function unless you know exactly why you're using it!

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/link

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
invoice_id	Integer	The ID of the master invoice
child_invoice_id	Integer	The ID of the child invoice

Success 200

Field	Type	Description
id	Integer	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Integer	The number of months of service this invoice was for
master_invoice_id	Integer	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
void	Boolean	Whether or not the invoice has been voided.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 12,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Reverse a credit

Reverse a credit on an invoice. You cannot reverse a credit if the accounting period is closed.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/credits/:credit_id/reverse

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice
credit_id	Number	The ID of the credit

Success 200

Field	Type	Description
id	Number	The ID of the credit
amount	Number	The amount of the credit, in system currency
void	Boolean	This will be true if the credit was reversed, or if the payment that created the credit is refunded or reversed
deposit_id	Number	If this was created by a deposit (payment) then this will be the ID of the deposit
discount_id	Number	If this was created by a discount, then this will be the ID of the discount
date	Date	The date the credit was applied, in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 263,
      "amount": 60.50,
      "void": false,
      "deposit_id": 5,
      "discount_id": 0,
      "date": "2015-09-23 16:55:13"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "The accounting period is closed."
         },
         "status_code": 422
     }
 }

Account_Invoices - Unfreeze invoice

Unfreeze an invoice. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/unfreeze

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet
void	Boolean	Whether or not the invoice has been voided.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Unfreeze invoice

Unfreeze an invoice. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/unfreeze

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice

Success 200

Field	Type	Description
id	Number	The internal ID of the invoice
date	Date	The date the invoice is for
frozen	Boolean	Whether or not the invoice is frozen
remaining_due	Number	How much is remaining to be paid on the invoice
child_remaining_due	Number	How much is remaining to be paid on any sub-account invoices linked to this one
number_of_months	Number	The number of months of service this invoice was for
master_invoice_id	Number	If this is an invoice on a sub account, this links to the master invoice that these charges roll up to
due_date	Date	The date after which this invoice is past due
delinquent	Boolean	Whether or not this invoice is delinquent
auto_pay	Date	The date on which auto pay will be attempted, if the user has an auto pay method on their account
auto_pay_attempted	Boolean	If this is true, auto pay has already been attempted. If not, it has not run yet

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Void invoice

Void an invoice. Voiding an invoice removes any credits applied from payments or discounts, and reverses all debits on the invoice. The reversed debits will be used to pay off the invoice.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/void

Parameter

Field	Type	Description
account_id	Number	The ID of the account
invoice_id	Number	The ID of the invoice.

Success 200

Field	Type	Description
success	Boolean	Will be `true` if the invoice was voided.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Invoice is already voided.",
     "status_code": 422
   }
 }

Account Payment Methods

Account_Payment_Methods - Create account payment method from an existing token

Create a new account payment method from an existing token. This should generally only be used when importing from another billing platform with existing tokens. You should ensure your Sonar system is already configured with the correct payment processor information before using this method. It is not possible for us to validate that the tokenized information is correct, so make sure you have done so on your side before submission.

https://example.sonar.software/api/v1/accounts/:account_id/tokenized_payment_method

Parameter

Field	Type	Description
account_id	Number	The ID of the account this payment method should exist on
payment_processor_customer_profile_id optional	String	If the payment processor being used stores a customer ID for their tokenization service, submit it here. This is optional, but must be included if the processor requires it
token	String	The existing token for the payment method
name_on_account	String	The name on the credit card, or the name on the bank account.
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`
identifier	String	This is generally the last few digits of the credit card or bank account. This should be a maximum of 4 characters
expiration_year	Number	Only required for credit cards, a 4 digit expiration year
expiration_month	Number	Only required for credit cards, a 2 digit expiration month
auto	Boolean	Whether or not this payment method should be set to auto pay
card_type	String	If this is a credit card, the type of card this is Allowed values: `"visaelectron"`, `"maestro"`, `"forbrugsforeningen"`, `"dankort"`, `"visa"`, `"mastercard"`, `"amex"`, `"dinersclub"`, `"discover"`, `"unionpay"`, `"jcb"`
line1	String	The address line of the credit card billing address. Only required if `type` is `credit card`.
city	String	City of the credit card billing address. Only required if `type` is `credit card`.
state	String	The state/province of the credit card billing address. Only required if `type` is `credit card`. You can obtain a valid list from _data/subdivisions/:country
zip	String	ZIP/postal code of the credit card billing address. Only required if `type` is `credit card`.
country	String	Two character ISO code of the country of the credit card billing address. Only required if `type` is `credit card`. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field	Type	Description
id	Number	The ID of the payment method
name_on_account	String	The name on the credit card, or the name on the bank account.
type	String	The type of payment method. Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account
line1	string	Line 1 of the credit card billing address.
city	string	The city of the credit card billing address.
state	string	The state/province of the credit card billing address.
zip	string	ZIP/postal code of the credit card billing address.
country	string	Two character ISO country code of the credit card billing address.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method from an existing token

https://example.sonar.software/api/v1/accounts/:account_id/tokenized_payment_method

Parameter

Field	Type	Description
account_id	Number	The ID of the account this payment method should exist on
payment_processor_customer_profile_id optional	String	If the payment processor being used stores a customer ID for their tokenization service, submit it here. This is optional, but must be included if the processor requires it
token	String	The existing token for the payment method
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`
identifier	String	This is generally the last few digits of the credit card or bank account. This should be a maximum of 4 characters
expiration_year	Number	Only required for credit cards, a 4 digit expiration year
expiration_month	Number	Only required for credit cards, a 2 digit expiration month
auto	Boolean	Whether or not this payment method should be set to auto pay
card_type	String	If this is a credit card, the type of card this is Allowed values: `"visaelectron"`, `"maestro"`, `"forbrugsforeningen"`, `"dankort"`, `"visa"`, `"mastercard"`, `"amex"`, `"dinersclub"`, `"discover"`, `"unionpay"`, `"jcb"`

Success 200

Field	Type	Description
id	Number	The ID of the payment method
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method

Create a new account payment method. Be cautious when using this method as you will be transmitting raw credit card or bank account data. You must ensure you take all necessary precautions to secure this data and that you understand the impact this may have on your PCI compliance.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the payment method to
type	String	The type of payment method being added Allowed values: `"credit card"`, `"bank account"`
expiration_month	Number	An integer representing the expiration month, if this is a credit card. 1 for January, 12 for December. Don't submit for bank accounts
expiration_year	Number	A four digit integer representing the expiration year, if this is a credit card. Don't submit for bank account
account_number	Number	For credit cards, this is the account number on the card, typically 16 digits but can be a different length. For bank accounts, this is the bank account number
cvc optional	Number	The CVC/CVV code from the credit card. Optional but recommended for credit cards, should be excluded otherwise. Some providers require this - in this case, it is not optional.
routing_number	Number	If this is a bank account, the routing number for the bank. Don't submit for credit cards
name_on_account	String	The name that is on the credit card, or the name that is on the bank account
account_type	String	If this is a bank account, submit one of 'checking' or 'savings'. Don't submit for credit cards Allowed values: `"checking"`, `"savings"`
auto	Boolean	Whether or not this payment method should be set to auto pay
line1	String	The address line of the credit card billing address. Only required if `type` is `credit card`.
city	String	City of the credit card billing address. Only required if `type` is `credit card`.
state	String	The state/province of the credit card billing address. Only required if `type` is `credit card`. You can obtain a valid list from _data/subdivisions/:country
zip	String	ZIP/postal code of the credit card billing address. Only required if `type` is `credit card`.
country	String	Two character ISO code of the country of the credit card billing address. Only required if `type` is `credit card`. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field	Type	Description
id	Number	The ID of the payment method
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the payment method to
type	String	The type of payment method being added Allowed values: `"credit card"`, `"bank account"`
expiration_month	Number	An integer representing the expiration month, if this is a credit card. 1 for January, 12 for December. Don't submit for bank accounts
expiration_year	Number	A four digit integer representing the expiration year, if this is a credit card. Don't submit for bank account
account_number	Number	For credit cards, this is the account number on the card, typically 16 digits but can be a different length. For bank accounts, this is the bank account number
routing_number	Number	If this is a bank account, the routing number for the bank. Don't submit for credit cards
name_on_account	String	The name that is on the credit card, or the name that is on the bank account
account_type	String	If this is a bank account, submit one of 'checking' or 'savings'. Don't submit for credit cards Allowed values: `"checking"`, `"savings"`
auto	Boolean	Whether or not this payment method should be set to auto pay
line1	String	The address line of the credit card billing address. Only required if `type` is `credit card`.
city	String	City of the credit card billing address. Only required if `type` is `credit card`.
state	String	The state/province of the credit card billing address. Only required if `type` is `credit card`. You can obtain a valid list from _data/subdivisions/:country
zip	String	ZIP/postal code of the credit card billing address. Only required if `type` is `credit card`.
country	String	Two character ISO code of the country of the credit card billing address. Only required if `type` is `credit card`. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field	Type	Description
id	Number	The ID of the payment method
name_on_account	String	The name on the credit card, if this is a credit card payment method.
type	String	The type of payment method. Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account
line1	string	Line 1 of the credit card billing address.
city	string	The city of the credit card billing address.
state	string	The state/province of the credit card billing address.
zip	string	ZIP/postal code of the credit card billing address.
country	string	Two character ISO country code of the credit card billing address.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the payment method to
type	String	The type of payment method being added Allowed values: `"credit card"`, `"bank account"`
expiration_month	Number	An integer representing the expiration month, if this is a credit card. 1 for January, 12 for December. Don't submit for bank accounts
expiration_year	Number	A four digit integer representing the expiration year, if this is a credit card. Don't submit for bank account
account_number	Number	For credit cards, this is the account number on the card, typically 16 digits but can be a different length. For bank accounts, this is the bank account number
routing_number	Number	If this is a bank account, the routing number for the bank. Don't submit for credit cards
name_on_account	String	The name that is on the credit card, or the name that is on the bank account
account_type	String	If this is a bank account, submit one of 'checking' or 'savings'. Don't submit for credit cards Allowed values: `"checking"`, `"savings"`
auto	Boolean	Whether or not this payment method should be set to auto pay
line1	String	The address line of the credit card billing address. Only required if `type` is `credit card`.
city	String	City of the credit card billing address. Only required if `type` is `credit card`.
state	String	The state/province of the credit card billing address. Only required if `type` is `credit card`. You can obtain a valid list from _data/subdivisions/:country
zip	String	ZIP/postal code of the credit card billing address. Only required if `type` is `credit card`.
country	String	Two character ISO code of the country of the credit card billing address. Only required if `type` is `credit card`. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field	Type	Description
id	Number	The ID of the payment method
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the payment method to
type	String	The type of payment method being added Allowed values: `"credit card"`, `"bank account"`
expiration_month	Number	An integer representing the expiration month, if this is a credit card. 1 for January, 12 for December. Don't submit for bank accounts
expiration_year	Number	A four digit integer representing the expiration year, if this is a credit card. Don't submit for bank account
account_number	Number	For credit cards, this is the account number on the card, typically 16 digits but can be a different length. For bank accounts, this is the bank account number
routing_number	Number	If this is a bank account, the routing number for the bank. Don't submit for credit cards
name_on_account	String	The name that is on the credit card, or the name that is on the bank account
account_type	String	If this is a bank account, submit one of 'checking' or 'savings'. Don't submit for credit cards Allowed values: `"checking"`, `"savings"`
auto	Boolean	Whether or not this payment method should be set to auto pay

Success 200

Field	Type	Description
id	Number	The ID of the payment method
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Delete account payment method

Delete an account payment method

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_method_id	Number	The ID of the payment method

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the payment method could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Account_Payment_Methods - Get all account payment methods

Get a list of the payment methods for account

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Success 200

Field	Type	Description
id	Number	The ID of the payment method
name_on_account	String	The name on the credit card, or the name on the bank account.
type	String	The type of payment method. Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account
line1	string	Line 1 of the credit card billing address.
city	string	The city of the credit card billing address.
state	string	The state/province of the credit card billing address.
zip	string	ZIP/postal code of the credit card billing address.
country	string	Two character ISO country code of the credit card billing address.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Payment_Methods - Get all account payment methods

Get a list of the payment methods for account

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the payment method
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 111,
      "type": "credit card",
      "identifier": "2333",
      "expiration_month": 8,
      "expiration_year": 2020,
      "auto": true
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Payment_Methods - Get individual account payment method

Get an individual account payment method.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_method_id	Number	The ID of the payment method

Success 200

Field	Type	Description
id	Number	The ID of the payment method
name_on_account	String	The name on the credit card, or the name on the bank account
type	String	The type of payment method. Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account
line1	string	Line 1 of the credit card billing address.
city	string	The city of the credit card billing address.
state	string	The state/province of the credit card billing address.
zip	string	ZIP/postal code of the credit card billing address.
country	string	Two character ISO country code of the credit card billing address.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Account_Payment_Methods - Get individual account payment method

Get an individual account payment method.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_method_id	Number	The ID of the payment method

Success 200

Field	Type	Description
id	Number	The ID of the payment method
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Account_Payment_Methods - Toggle the auto payment setting

Toggle the automatic payment flag on a payment method. Only one payment method can be auto at a time - enabling auto on a method will disable auto on all other methods.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:id/toggle_auto

Parameter

Field Type Description

account_id

Integer

The ID of the account

Integer

The ID of the payment method

auto

Boolean

The automatic payment state of the payment method

Default value: false

Success 200

Field	Type	Description
id	Number	The ID of the payment method
name_on_account	String	The name on the credit card, or the name on the bank account.
type	String	The type of payment method. Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account
line1	string	Line 1 of the credit card billing address.
city	string	The city of the credit card billing address.
state	string	The state/province of the credit card billing address.
zip	string	ZIP/postal code of the credit card billing address.
country	string	Two character ISO country code of the credit card billing address.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "auto": "auto must be a boolean.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Update stored credit card

Update a stored credit card on an account.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account to update the address on
payment_method_id	Number	The ID of the payment method
name_on_account	String	The name on the credit card.
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December.
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards.
auto	Boolean	Whether or not this should be an automatic payment method. Setting auto to `true` on a payment method will unset auto on any other payment methods on the account
line1	String	The address line of the credit card billing address.
city	String	City of the credit card billing address.
state	String	The state/province of the credit card billing address.. You can obtain a valid list from _data/subdivisions/:country
zip	String	ZIP/postal code of the credit card billing address..
country	String	Two character ISO code of the country of the credit card billing address.. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field	Type	Description
id	Number	The ID of the payment method
name_on_account	String	The name on the credit card
type	String	The type of payment method, will always be `credit card`. Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account
line1	string	Line 1 of the credit card billing address.
city	string	The city of the credit card billing address.
state	string	The state/province of the credit card billing address.
zip	string	ZIP/postal code of the credit card billing address.
country	string	Two character ISO country code of the credit card billing address.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "auto": "The selected value is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Update account payment method

Update an account payment method. Currently, the only thing that can be changed is whether or not the payment method is an auto-pay method. If you need to modify a payment method, delete the existing one and create a new one

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account to update the address on
payment_method_id	Number	The ID of the payment method
auto	Boolean	Whether or not this should be an automatic payment method. Setting auto on a payment method will unset auto on any other payment methods on the account

Success 200

Field	Type	Description
id	Number	The ID of the payment method
type	String	The type of payment method Allowed values: `"credit card"`, `"echeck"`, `"ach"`
identifier	String	Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits
expiration_month	Number	A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December
expiration_year	Number	A 4 digit integer representing the expiration year for credit cards
auto	Boolean	Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "auto": "The selected value is not valid.",
         },
         "status_code": 422
     }
 }

Account Services

Account_Services - Add a package to an account

Add a package to an account. A package is a group of recurring and/or expiring services. This will return a random, unique ID. This ID can be used to delete the package later. This unique ID is used to allow the account to have multiple instances of the same package, but still differentiate between them.

https://example.sonar.software/api/v1/accounts/:account_id/packages

Parameter

Field Type Description

account_id

Number

The ID of the account to add the package to

package_id

Number

The ID of the package you wish to add

prorate

Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false'

Default value: false

Success 200

Field	Type	Description
unique_package_id	Boolean	This unique ID will be attached to all services on the account list that are part of this specific package. You need this ID to remove the package later.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "unique_package_id": "5787b0cc6b25f"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "One of the services in the package is inactive.",
         "status_code": 422
     }
 }

Account_Services - Add a package to an account

Add a package to an account. A package is a group of recurring and/or expiring services

https://example.sonar.software/api/v1/accounts/:account_id/packages

Parameter

Field Type Description

account_id

Number

The ID of the account to add the package to

package_id

Number

The ID of the package you wish to add

prorate

Boolean

Default value: false

Success 200

Field	Type	Description
success	Boolean	If this is true, the process was completed successfully. If there are any errors, you will receive a non-2xx HTTP response code and an error object

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "One of the services in the package is inactive.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the address to
service_id	Number	The ID of the service you wish to add
description optional	String	If you are entering a one time charge/adjustment, you can enter a description here to override the service name. This will show up on customer invoices!
quantity optional	Number	If you are submitting a one time service, this is the quantity to add. If the one time service is $50, and this value is '3', a single transaction will be created for $150. If this is for a recurring service, the service will be added with this quantity for prorating, and future billing. Default value: `1`
prorate optional	Boolean	Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.
amount optional	Number	This is only valid for adjustment services, and is required if you are submitting one. This is the amount you wish to adjust the account by.
price_override optional	Number	The amount to price override the service to. Only valid for recurring/expiring services.
price_override_reason optional	String	The reason for applying the price override. Only valid for recurring/expiring services.
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
next_bill_date optional	Date	The next date this service will bill. Only valid for multi-month services. If unset, it will bill on the next account billing date.
service_metadata optional	Array	An array of objects, each object should have an 'id' and 'value' property, where the 'id' is the ID of a service metadata field, and the 'value' is the value you wish to set the field to.

Success 200

Field	Type	Description
unique_service_relationship_id	Number	The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the address to
service_id	Number	The ID of the service you wish to add
description optional	String	If you are entering a one time charge/adjustment, you can enter a description here to override the service name. This will show up on customer invoices!
quantity optional	Number	If you are submitting a one time service, this is the quantity to add. If the one time service is $50, and this value is '3', a single transaction will be created for $150. If this is for a recurring service, the service will be added with this quantity for prorating, and future billing. Default value: `1`
prorate optional	Boolean	Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.
amount optional	Number	This is only valid for adjustment services, and is required if you are submitting one. This is the amount you wish to adjust the account by.
price_override optional	Number	The amount to price override the service to. Only valid for recurring/expiring services.
price_override_reason optional	String	The reason for applying the price override. Only valid for recurring/expiring services.
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
service_metadata optional	Array	An array of objects, each object should have an 'id' and 'value' property, where the 'id' is the ID of a service metadata field, and the 'value' is the value you wish to set the field to.

Success 200

Field	Type	Description
unique_service_relationship_id	Number	The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the address to
service_id	Number	The ID of the service you wish to add
description optional	String	If you are entering a one time charge/adjustment, you can enter a description here to override the service name. This will show up on customer invoices!
quantity optional	Number	If you are submitting a one time service, this is the quantity to add. If the one time service is $50, and this value is '3', a single transaction will be created for $150. If this is for a recurring service, the service will be added with this quantity for prorating, and future billing. Default value: `1`
prorate optional	Boolean	Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.
amount optional	Number	This is only valid for adjustment services, and is required if you are submitting one. This is the amount you wish to adjust the account by.
price_override optional	Number	The amount to price override the service to. Only valid for recurring/expiring services.
price_override_reason optional	String	The reason for applying the price override. Only valid for recurring/expiring services.
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success 200

Field	Type	Description
unique_service_relationship_id	Number	The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the address to
service_id	Number	The ID of the service you wish to add
description optional	String	If you are entering a one time charge/adjustment, you can enter a description here to override the service name. This will show up on customer invoices!
quantity optional	Number	If you are submitting a one time service, this is the quantity to add. If the one time service is $50, and this value is '3', a single transaction will be created for $150. Ignored for any non-one time services. Default value: `1`
prorate optional	Boolean	Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.
amount optional	Number	This is only valid for adjustment services, and is required if you are submitting one. This is the amount you wish to adjust the account by.
price_override optional	Number	The amount to price override the service to. Only valid for recurring/expiring services.
price_override_reason optional	String	The reason for applying the price override. Only valid for recurring/expiring services.
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success 200

Field	Type	Description
unique_service_relationship_id	Number	The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the address to
service_id	Number	The ID of the service you wish to add
prorate	Boolean	Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false' Default value: `false`
amount	Number	This is only valid for adjustment services. This is the amount you wish to adjust the account by.
price_override optional	Number	The amount to price override the service to. Only valid for recurring/expiring services.
price_override_reason optional	String	The reason for applying the price override. Only valid for recurring/expiring services.

Success 200

Field	Type	Description
unique_service_relationship_id	Number	The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account to add the address to
service_id	Number	The ID of the service you wish to add
prorate	Boolean	Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false' Default value: `false`
amount	Number	This is only valid for adjustment services. This is the amount you wish to adjust the account by

Success 200

Field	Type	Description
success	Boolean	If this is true, the process was completed successfully. If there are any errors, you will receive a non-2xx HTTP response code and an error object

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Delete a package from an account

Delete a package from an account. A package is a group of recurring and/or expiring services

https://example.sonar.software/api/v1/accounts/:account_id/packages/:unique_package_id

Parameter

Field Type Description

account_id

Number

The ID of the account to delete the package from

unique_package_id

Number

The unique ID returned when the package was added.

prorate

Boolean

Default value: false

Success 200

Field	Type	Description
success	Boolean	If this is true, the process was completed successfully. If there are any errors, you will receive a non-2xx HTTP response code and an error object

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "One of the services in the package is inactive.",
         "status_code": 422
     }
 }

Account_Services - Delete a package from an account

Delete a package from an account. A package is a group of recurring and/or expiring services

https://example.sonar.software/api/v1/accounts/:account_id/packages/:package_id

Parameter

Field Type Description

account_id

Number

The ID of the account to delete the package from

package_id

Number

The ID of the package you wish to delete

prorate

Boolean

Default value: false

Success 200

Field	Type	Description
success	Boolean	If this is true, the process was completed successfully. If there are any errors, you will receive a non-2xx HTTP response code and an error object

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "One of the services in the package is inactive.",
         "status_code": 422
     }
 }

Account_Services - Delete account service

Delete a service from an account. Only valid for recurring/expiring services

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description

account_id

Number

The ID of the account

unique_service_relationship_id

Number

The unique relationship ID of the service

prorate

Boolean

Default value: false

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the service could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity	Integer	The quantity of this particular service instance
next_bill_date	Date	The next date this service will bill. If `null`, it will bill on the next account billing date.
metadata	Object	An object where the property is the metadata ID, and the value is the metadata value.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null,
      "quantity": 1,
      "next_bill_date": "2018-11-06",
      "metadata": {}
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com",
      "quantity": 12,
      "next_bill_date": "2018-11-06",
      "metadata": {
           "12": "test"
      }
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity	Integer	The quantity of this particular service instance
metadata	Object	An object where the property is the metadata ID, and the value is the metadata value.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null,
      "quantity": 1,
      "metadata": {}
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com",
      "quantity": 12,
      "metadata": {
           "12": "test"
      }
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity	Integer	The quantity of this particular service instance
service_id	Integer	The ID of the service
account_id	Integer	The ID of the account

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null,
      "quantity": 1,
      "service_id": 4,
      "account_id": 3
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com",
      "quantity": 12,
      "service_id": 1,
      "account_id": 6
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity	Integer	The quantity of this particular service instance

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null,
      "quantity": 1
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com",
      "quantity": 12
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_service_relationship_id": 8
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_service_relationship_id": 10
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account

Success 200

Field	Type	Description
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity	Integer	The quantity of this particular service instance
next_bill_date	Date	The next date this service will bill. If `null`, it will bill on the next account billing date.
metadata	Object	An object where the property is the metadata ID, and the value is the metadata value.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "quantity": 5,
    "next_bill_date": null,
    "metadata": {
         "12": "test"
    }
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account

Success 200

Field	Type	Description
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity	Integer	The quantity of this particular service instance
metadata	Object	An object where the property is the metadata ID, and the value is the metadata value.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "quantity": 5,
    "metadata": {
         "12": "test"
    }
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account

Success 200

Field	Type	Description
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity	Integer	The quantity of this particular service instance
service_id	Integer	The ID of the service
account_id	Integer	The ID of the account

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "quantity": 5,
    "service_id": 5,
    "account_id": 1
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account

Success 200

Field	Type	Description
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity	Integer	The quantity of this particular service instance

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "quantity": 5
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account

Success 200

Field	Type	Description
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account

Success 200

Field	Type	Description
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_service_relationship_id": 10
  }
}

Account_Services - Get usage based billing policy details

Get details on any usage based billing policy that may be applied to the customer account, along with some other useful details.

https://example.sonar.software/api/v1/accounts/:id/usage_based_billing_policy_details

Parameter

Field	Type	Description
id	Number	The internal ID of the account

Success 200

Field	Type	Description
has_policy	Boolean	Does the account have a usage based billing policy being applied to it?
policy_cap_in_gigabytes	Number	The cap on the policy in gigabytes. This does not include any rollover or top offs.
rollover_enabled	Boolean	Is the rollover feature enabled on this policy?
rollover_expiration_enabled	Boolean	Does rollover data expire?
rollover_expires_after_months	Number	If `rollover_expiration` is true, this is the number of months after which rollover data expires.
assess_charges_at_end_of_billing_period	Boolean	If this is true, the customer will be charged for overages at the end of the billing period based on the values in overage_cost and overage_units_in_gigabytes.
allow_user_to_purchase_capacity	Boolean	If this is true, the customer can purchase additional capacity during his billing cycle based on the values in overage_cost and overage_units_in_gigabytes.
overage_cost	Number	The cost of overages on this policy.
overage_units_in_gigabytes	Number	This is the amount of data provided for the cost defined in `overage_cost`. E.g. if this is 5 and `overage_cost` is 10, then $10 provides 5 gigabytes.
rollover_available_in_bytes	Number	If `rollover_enabled` is true, then this is the amount of additional data available in the current billing period.
purchased_top_off_total_in_bytes	Number	If `allow_user_to_purchase_capacity` is true, then this is the amount of additional data purchased in the current billing period.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "has_policy": true,
    "policy_cap_in_gigabytes": 1,
    "rollover_enabled": true,
    "rollover_expiration_enabled": false,
    "rollover_expires_after_months": 0,
    "assess_charges_at_end_of_billing_period": false,
    "allow_user_to_purchase_capacity": false,
    "overage_cost": null,
    "overage_units_in_gigabytes": null,
    "rollover_available_in_bytes": 10000000000,
    "purchased_top_off_total_in_bytes": 0
  }
}

Account_Services - Update account service

Update an account service. The only values that can be changed are the price override, price override reason, and name override. To remove a price override or name override, set the price_override property to null.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
unique_service_relationship_id	Number	The unique relationship ID of the service that already exists on the account
price_override optional	Number	The amount to price override the service by
price_override_reason optional	String	The reason for applying the price override
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity optional	Integer	If this is set, the quantity of the service will be adjusted to this amount. Must be 1 or greater.
prorate optional	Boolean	Whether or not you want to prorate this transaction, only valid if you are changing the quantity. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.
next_bill_date optional	Date	The next date this service will bill. Only valid for multi-month services. If unset, it will bill on the next account billing date.
service_metadata optional	Array	An array of objects, each object should have an 'id' and 'value' property, where the 'id' is the ID of a service metadata field, and the 'value' is the value you wish to set the field to.

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
next_bill_date	Date	The next date this service will bill. If `null`, it will bill on the next account billing date.
metadata	Object	An object where the property is the metadata ID, and the value is the metadata value.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "next_bill_date": null,
    "metadata": {
       "1": "test!!!123!",
       "2": "another test",
       "3": null
    }
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
unique_service_relationship_id	Number	The unique relationship ID of the service that already exists on the account
price_override optional	Number	The amount to price override the service by
price_override_reason optional	String	The reason for applying the price override
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity optional	Integer	If this is set, the quantity of the service will be adjusted to this amount. Must be 1 or greater.
prorate optional	Boolean	Whether or not you want to prorate this transaction, only valid if you are changing the quantity. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.
service_metadata optional	Array	An array of objects, each object should have an 'id' and 'value' property, where the 'id' is the ID of a service metadata field, and the 'value' is the value you wish to set the field to.

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
metadata	Object	An object where the property is the metadata ID, and the value is the metadata value.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "metadata": {
       "1": "test!!!123!",
       "2": "another test",
       "3": null
    }
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
unique_service_relationship_id	Number	The unique relationship ID of the service that already exists on the account
price_override optional	Number	The amount to price override the service by
price_override_reason optional	String	The reason for applying the price override
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity optional	Integer	If this is set, the quantity of the service will be adjusted to this amount. Must be 1 or greater.
prorate optional	Boolean	Whether or not you want to prorate this transaction, only valid if you are changing the quantity. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
service_id	Integer	The ID of the service
account_id	Integer	The ID of the account

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "service_id": 4,
    "account_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
unique_service_relationship_id	Number	The unique relationship ID of the service that already exists on the account
price_override optional	Number	The amount to price override the service by
price_override_reason optional	String	The reason for applying the price override
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.
quantity optional	Integer	If this is set, the quantity of the service will be adjusted to this amount. Must be 1 or greater.
prorate optional	Boolean	Whether or not you want to prorate this transaction, only valid if you are changing the quantity. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
unique_service_relationship_id	Number	The unique relationship ID of the service that already exists on the account
price_override optional	Number	The amount to price override the service by
price_override_reason optional	String	The reason for applying the price override
name_override optional	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_package_id	String	If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account
name_override	String	If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

Update an account service. The only values that can be changed are the price override and price override reason. To remove a price override, set the price_override property to null

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
unique_service_relationship_id	Number	The unique relationship ID of the service that already exists on the account
price_override	Number	The amount to price override the service by
price_override_reason	String	The reason for applying the price override

Success 200

Field	Type	Description
id	Number	The internal ID of the service. You can use this to retrieve service details from the /services endpoint
number_of_times_billed	Number	Only valid for expiring services, this is the number of times the service has been run
price_override	Number	If the service has a price override on it, it will be represented here. Otherwise, this will be null
price_override_reason	String	If the service has a price override, the optional reason will be displayed here
package_id	Number	If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself
unique_service_relationship_id	Number	This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_service_relationship_id": 10
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account Tax Overrides

Account_Tax_Overrides - Create a new account tax override

Create a new account tax override. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides

Parameter

Field	Type	Description
account_id	Integer	The account ID
tax_id	Integer	The ID of the tax to override
rate	Number	The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

Success 200

Field	Type	Description
id	Integer	The tax override ID
account_id	Integer	The account ID
tax_id	Integer	The ID of the tax to override
rate	Number	The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "tax_id": 3,
    "account_id": 12,
    "rate": 15.43234
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "tax_id": "The tax ID is invalid."
     },
     "status_code": 422
   }
 }

Account_Tax_Overrides - Delete an account tax override

Delete an account tax override. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
id	Integer	The ID of the account tax override

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the account tax override could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "account tax override does not exist.",
         "status_code": 404
     }
 }

Account_Tax_Overrides - Get all account tax overrides

Get all account tax overrides. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return
account_id	Integer	The ID of the account

Success 200

Field	Type	Description
id	Integer	The tax override ID
account_id	Integer	The account ID
tax_id	Integer	The ID of the tax to override
rate	Number	The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "tax_id": 3,
      "account_id": 12,
      "rate": 15.43234
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Tax_Overrides - Get an individual account tax override

Get an individual account tax override. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
id	Integer	The ID of the account tax override

Success 200

Field	Type	Description
id	Integer	The tax override ID
account_id	Integer	The account ID
tax_id	Integer	The ID of the tax to override
rate	Number	The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "tax_id": 3,
    "account_id": 12,
    "rate": 15.43234
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_Tax_Overrides - Update account tax override

Update an existing account tax override. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides/:id

Parameter

Field	Type	Description
id	Integer	The ID of the tax override
account_id	Integer	The account ID
tax_id	Integer	The ID of the tax to override
rate	Number	The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

Success 200

Field	Type	Description
id	Integer	The tax override ID
account_id	Integer	The account ID
tax_id	Integer	The ID of the tax to override
rate	Number	The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "tax_id": 3,
    "account_id": 12,
    "rate": 15.43234
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account Transactions

Account_Transactions - Apply an external PayPal payment

Store an externally made PayPal payment into Sonar. This should only be used to store PayPal payments made using the same PayPal API credentials as you have entered in Sonar. This endpoint is mostly designed to implement things like an external customer portal.

https://example.sonar.software/api/v1/accounts/:id/transactions/paypal_payments

Parameter

Field	Type	Description
id	Number	The ID of the account
amount	Number	The amount of the successful PayPal payment
transaction_id	String	The transaction ID of the PayPal payment. This is the sale ID provided in the returned transaction list from PayPal. It is important this is correct, or attempts to refund inside Sonar will fail.

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"paypal"`
response_message	String	Will be 'APPROVED'
success	Boolean	Will always be true in this scenario
reversed	Boolean	This will be true if the payment reversed successfully
reversed_at	Date	This will be the current date if the payment was reversed successfully
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "amount": 12.53,
    "payment_method_id": 0,
    "type": "paypal",
    "response_message": "APPROVED",
    "transaction_id": "ABC123",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2016-06-01 18:23:02"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "PayPal processing is not enabled.",
     "status_code": 422
   }
 }

Account_Transactions - Create payment

Create a payment. If you submit a payment method ID, this will use the payment processor for the payment method to run the payment in real time. If you do not, it will add a payment via whatever method you specify.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_method_id optional	Number	The ID of the payment method to use to make the payment. If this is omitted, payment_method must be specified
payment_method optional	String	A string representing the type of payment this is. If payment_method_id is included, this is ignored Allowed values: `"cash"`, `"check"`, `"wire"`
reference optional	String	If you're submitting a cash, check or wire payment, you can submit a string here that will be stored as a reference. If you're using a payment_method_id, this will be ignored, as the message stored will be the response from the payment processor.
amount	Number	The amount of the payment to post. This should be a decimal in the format xx.yy (e.g. 10.32 or 134.23)
auto_apply	Boolean	Whether or not to automatically apply this payment to any outstanding invoices. If this is false, you will need to manually apply this payment to invoices to reduce their due balance Default value: `true`
date optional	Date	The date the payment should be applied for. Cannot be in the future, and is ignored for payments made via a payment method. If null, the current date will be used.

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`
response_message	String	The response message from the payment processor, if one was used for this transaction
transaction_id	String	The transaction ID from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	This will be true if the payment reversed successfully
reversed_at	Date	This will be the current date if the payment was reversed successfully
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Create payment

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_method_id optional	Number	The ID of the payment method to use to make the payment. If this is omitted, payment_method must be specified
payment_method optional	String	A string representing the type of payment this is. If payment_method_id is included, this is ignored Allowed values: `"cash"`, `"check"`, `"wire"`
reference optional	String	If you're submitting a cash, check or wire payment, you can submit a string here that will be stored as a reference. If you're using a payment_method_id, this will be ignored, as the message stored will be the response from the payment processor.
amount	Number	The amount of the payment to post. This should be a decimal in the format xx.yy (e.g. 10.32 or 134.23)
auto_apply	Boolean	Whether or not to automatically apply this payment to any outstanding invoices. If this is false, you will need to manually apply this payment to invoices to reduce their due balance Default value: `true`

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`
response_message	String	The response message from the payment processor, if one was used for this transaction
transaction_id	String	The transaction ID from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	This will be true if the payment reversed successfully
reversed_at	Date	This will be the current date if the payment was reversed successfully
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Create payment

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_method_id optional	Number	The ID of the payment method to use to make the payment. If this is omitted, payment_method must be specified
payment_method optional	String	A string representing the type of payment this is. If payment_method_id is included, this is ignored Allowed values: `"cash"`, `"check"`, `"wire"`
reference optional	String	If you're submitting a cash, check or wire payment, you can submit a string here that will be stored as a reference. If you're using a payment_method_id, this will be ignored, as the message stored will be the response from the payment processor.
amount	Number	The amount of the payment to post. This should be a decimal in the format xx.yy (e.g. 10.32 or 134.23)
auto_apply	Boolean	Whether or not to automatically apply this payment to any outstanding invoices. If this is false, you will need to manually apply this payment to invoices to reduce their due balance Default value: `true`

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	This will be true if the payment reversed successfully
reversed_at	Date	This will be the current date if the payment was reversed successfully
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Edit account payment

Edit a payment. You can only change the reference on a wire, cash, check, or other payment.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
id	Number	The ID of the payment
response_message optional	String	The reference you want to store for this payment

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	If this payment is refunded/reversed, this will be true
reversed_at	Date	If a payment is refunded/reversed, this will be the date the reversal occurs
date	Date	The date the payment was applied

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "amount": 1,
    "payment_method_id": null,
    "type": "check",
    "response_message": "test",
    "transaction_id": null,
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2016-07-10 18:43:28"
  }
}

Account_Transactions - Edit debit description

Edit the description on a debit

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits/:debit_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
debit_id	Number	The ID of the debit
description optional	String	The description to overwrite the existing description with. Send null to remove it and revert to the service name.

Success 200

Field	Type	Description
id	Number	An ID representing the individual debit
amount	Number	The amount of the debit in the system currency
invoice_id	Number	The invoice the debit is associated with, if it is associated with an invoice. Null otherwise
service_id	Number	The ID of the service that the debit is associated with
date	Date	The date and time the debit was created in UTC
reversed	Boolean	If this is true, the debit has been reversed
reversed_at	Date	If reversed is true, this is the date the debit was reversed
discount_id	Number	If reversed is true, this is the ID of the discount that was created to reverse the debit
number_of_months	Number	If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged
description	String	A description for the transaction, if one was set. The name of the service that generated it, otherwise.
quantity	Number	If this was a one time transaction, this is the number of applications that created this single transaction. Default value: `1`
general_ledger_code	String	The general ledger code for this transaction
general_ledger_code_description	String	The description for the general ledger code for this transaction

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 200,
    "amount": 186.48,
    "invoice_id": 241,
    "service_id": 6,
    "date": "2015-09-17 01:48:46",
    "reversed": true,
    "reversed_at": "2015-09-22",
    "discount_id": 265,
    "number_of_months": 3,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ],
    "description": "Fast Internet",
    "quantity": 1,
    "general_ledger_code": "1000",
    "general_ledger_code_description": "test test"
  }
}

Account_Transactions - Edit discount description

Edit the description on a discount

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts/:discount_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
discount_id	Number	The ID of the discount
description optional	String	The description to overwrite the existing description with. Send null to revert back to the service name.

Success 200

Field	Type	Description
id	Number	An ID representing the individual discount
amount	Number	The amount of the discount in the system currency
amount_remaining	Number	How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount
service_id	Number	The ID of the service that the discount is associated with
date	Date	The date and time the discount was created in UTC
reversed	Boolean	If this is true, the discount has been reversed
reversed_at	Date	If reversed is true, this is the date the discount was reversed
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit
description	String	A description for the transaction, if one was set. The name of the service that generated it, otherwise.
quantity	Number	If this was a one time transaction, this is the number of applications that created this single transaction. Default value: `1`
general_ledger_code	String	The general ledger code for this transaction
general_ledger_code_description	String	The description for the general ledger code for this transaction

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 265,
    "amount": 186.48,
    "amount_remaining": 198.48,
    "service_id": 6,
    "date": "2015-09-22 03:03:17",
    "reversed": false,
    "reversed_at": null,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ],
    "description": "Service name",
    "quantity": 1,
    "general_ledger_code": "1000",
    "general_ledger_code_description": "test test"
  }
}

Account_Transactions - Get all account debits

Get a list of the debits on the account.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	An ID representing the individual debit
amount	Number	The amount of the debit in the system currency
invoice_id	Number	The invoice the debit is associated with, if it is associated with an invoice. Null otherwise
service_id	Number	The ID of the service that the debit is associated with
date	Date	The date and time the debit was created in UTC
reversed	Boolean	If this is true, the debit has been reversed
reversed_at	Date	If reversed is true, this is the date the debit was reversed
discount_id	Number	If reversed is true, this is the ID of the discount that was created to reverse the debit
number_of_months	Number	If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged
description	String	A description for the transaction, if one was set. The name of the service that generated it, otherwise.
quantity	Number	If this was a one time transaction, this is the number of applications that created this single transaction. Default value: `1`
general_ledger_code	String	The general ledger code for this transaction
general_ledger_code_description	String	The description for the general ledger code for this transaction

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 200,
      "amount": 186.48,
      "invoice_id": 241,
      "service_id": 6,
      "date": "2015-09-17 01:48:46",
      "reversed": true,
      "reversed_at": "2015-09-22",
      "discount_id": 265,
      "number_of_months": 3,
      "taxes": [
        {
          "description": "Sales Tax",
          "amount": 9
        },
        {
          "description": "Some Other Tax",
          "amount": 3
        }
      ],
      "description": "Some Service",
      "quantity": 1
    },
    {
      "id": 201,
      "amount": 181.50,
      "invoice_id": 241,
      "service_id": 7,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "discount_id": null,
      "number_of_months": 3,
      "taxes": [],
      "description": "Look ma, no hands!",
      "quantity": 3,
      "general_ledger_code": "1000",
      "general_ledger_code_description": "test test"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account debits

Get a list of the debits on the account.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	An ID representing the individual debit
amount	Number	The amount of the debit in the system currency
invoice_id	Number	The invoice the debit is associated with, if it is associated with an invoice. Null otherwise
service_id	Number	The ID of the service that the debit is associated with
date	Date	The date and time the debit was created in UTC
reversed	Boolean	If this is true, the debit has been reversed
reversed_at	Date	If reversed is true, this is the date the debit was reversed
discount_id	Number	If reversed is true, this is the ID of the discount that was created to reverse the debit
number_of_months	Number	If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 200,
      "amount": 186.48,
      "invoice_id": 241,
      "service_id": 6,
      "date": "2015-09-17 01:48:46",
      "reversed": true,
      "reversed_at": "2015-09-22",
      "discount_id": 265,
      "number_of_months": 3,
      "taxes": [
        {
          "description": "Sales Tax",
          "amount": 9
        },
        {
          "description": "Some Other Tax",
          "amount": 3
        }
      ]
    },
    {
      "id": 201,
      "amount": 181.50,
      "invoice_id": 241,
      "service_id": 7,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "discount_id": null,
      "number_of_months": 3,
      "taxes": []
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account deposits

Get a list of the deposits on the account. A deposit is created by a payment being applied to an account. The payment itself is tracked separately and is available at the /payments endpoint

https://example.sonar.software/api/v1/accounts/:account_id/transactions/deposits

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	An ID representing the individual deposit
amount	Number	The amount of the deposit in the system currency
amount_remaining	Number	How much of the deposit has not been applied as credits on invoices
payment_id	Number	The ID of the payment that the deposit was created by
void	Boolean	If a payment is reversed, the deposit will be void
date	Date	The date and time the discount was created in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "amount": 55.39,
      "amount_remaining": 0.00,
      "payment_id": 3,
      "void": false,
      "date": "2015-09-23 16:55:12"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account discounts

Get a list of the discounts on the account.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	An ID representing the individual discount
amount	Number	The amount of the discount in the system currency
amount_remaining	Number	How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount
service_id	Number	The ID of the service that the discount is associated with
date	Date	The date and time the discount was created in UTC
reversed	Boolean	If this is true, the discount has been reversed
reversed_at	Date	If reversed is true, this is the date the discount was reversed
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit
description	String	A description for the transaction, if one was set. The name of the service that generated it, otherwise.
quantity	Number	If this was a one time transaction, this is the number of applications that created this single transaction. Default value: `1`
general_ledger_code	String	The general ledger code for this transaction
general_ledger_code_description	String	The description for the general ledger code for this transaction

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 265,
      "amount": 186.48,
      "amount_remaining": "198.48",
      "service_id": 6,
      "date": "2015-09-22 03:03:17",
      "reversed": false,
      "reversed_at": null,
      "taxes": [
        {
          "description": "Sales Tax",
          "amount": 9
        },
        {
          "description": "Other Tax",
          "amount": 3
        }
      ],
      "description": "Some description",
      "quantity": 1,
      "general_ledger_code": null,
      "general_ledger_code_description": null
    },
    {
      "id": 227,
      "amount": 214.53,
      "amount_remaining": 0.00,
      "service_id": 2,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "taxes": []
    },
    {
      "id": 228,
      "amount": 167.43,
      "amount_remaining": 1.98,
      "service_id": 10,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "taxes": [],
      "description": "Installation Credit",
      "quantity": 1,
      "general_ledger_code": null,
      "general_ledger_code_description": null
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account discounts

Get a list of the discounts on the account.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	An ID representing the individual discount
amount	Number	The amount of the discount in the system currency
amount_remaining	Number	How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount
service_id	Number	The ID of the service that the discount is associated with
date	Date	The date and time the discount was created in UTC
reversed	Boolean	If this is true, the discount has been reversed
reversed_at	Date	If reversed is true, this is the date the discount was reversed
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 265,
      "amount": 186.48,
      "amount_remaining": "198.48",
      "service_id": 6,
      "date": "2015-09-22 03:03:17",
      "reversed": false,
      "reversed_at": null,
      "taxes": [
        {
          "description": "Sales Tax",
          "amount": 9
        },
        {
          "description": "Other Tax",
          "amount": 3
        }
      ]
    },
    {
      "id": 227,
      "amount": 214.53,
      "amount_remaining": 0.00,
      "service_id": 2,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "taxes": []
    },
    {
      "id": 228,
      "amount": 167.43,
      "amount_remaining": 1.98,
      "service_id": 10,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "taxes": []
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account payments

Get a list of the payments on the account. A payment creates a deposit

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
transaction_id	String	The transaction ID from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	If this payment is refunded/reversed, this will be true
reversed_at	Date	If a payment is refunded/reversed, this will be the date the reversal occurs
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "amount": 55.39,
      "payment_method_id": 111,
      "type": "credit card",
      "response_message": "Successful.",
      "transaction_id": "12345ABC",
      "success": true,
      "reversed": false,
      "reversed_at": null,
      "date": "2015-09-23 16:55:12"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account payments

Get a list of the payments on the account. A payment creates a deposit

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field	Type	Description
account_id	Number	The ID of the account
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	If this payment is refunded/reversed, this will be true
reversed_at	Date	If a payment is refunded/reversed, this will be the date the reversal occurs
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "amount": 55.39,
      "payment_method_id": 111,
      "type": "credit card",
      "response_message": "Successful.",
      "success": true,
      "reversed": false,
      "reversed_at": null,
      "date": "2015-09-23 16:55:12"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get individual account debit

Get an individual account debit by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits/:debit_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
debit_id	Number	The ID of the debit

Success 200

Field	Type	Description
id	Number	An ID representing the individual debit
amount	Number	The amount of the debit in the system currency
invoice_id	Number	The invoice the debit is associated with, if it is associated with an invoice. Null otherwise
service_id	Number	The ID of the service that the debit is associated with
date	Date	The date and time the debit was created in UTC
reversed	Boolean	If this is true, the debit has been reversed
reversed_at	Date	If reversed is true, this is the date the debit was reversed
discount_id	Number	If reversed is true, this is the ID of the discount that was created to reverse the debit
number_of_months	Number	If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged
description	String	A description for the transaction, if one was set. The name of the service that generated it, otherwise.
quantity	Number	If this was a one time transaction, this is the number of applications that created this single transaction. Default value: `1`
general_ledger_code	String	The general ledger code for this transaction
general_ledger_code_description	String	The description for the general ledger code for this transaction

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 200,
    "amount": 186.48,
    "invoice_id": 241,
    "service_id": 6,
    "date": "2015-09-17 01:48:46",
    "reversed": true,
    "reversed_at": "2015-09-22",
    "discount_id": 265,
    "number_of_months": 3,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ],
    "description": "Some service name",
    "quantity": 1,
    "general_ledger_code": "1000",
    "general_ledger_code_description": "test test"
  }
}

Account_Transactions - Get individual account debit

Get an individual account debit by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits/:debit_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
debit_id	Number	The ID of the debit

Success 200

Field	Type	Description
id	Number	An ID representing the individual debit
amount	Number	The amount of the debit in the system currency
invoice_id	Number	The invoice the debit is associated with, if it is associated with an invoice. Null otherwise
service_id	Number	The ID of the service that the debit is associated with
date	Date	The date and time the debit was created in UTC
reversed	Boolean	If this is true, the debit has been reversed
reversed_at	Date	If reversed is true, this is the date the debit was reversed
discount_id	Number	If reversed is true, this is the ID of the discount that was created to reverse the debit
number_of_months	Number	If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 200,
    "amount": 186.48,
    "invoice_id": 241,
    "service_id": 6,
    "date": "2015-09-17 01:48:46",
    "reversed": true,
    "reversed_at": "2015-09-22",
    "discount_id": 265,
    "number_of_months": 3,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ]
  }
}

Account_Transactions - Get individual account deposit

Get an individual account deposit by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/deposits/:deposit_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
deposit_id	Number	The ID of the deposit

Success 200

Field	Type	Description
id	Number	An ID representing the individual deposit
amount	Number	The amount of the deposit in the system currency
amount_remaining	Number	How much of the deposit has not been applied as credits on invoices
payment_id	Number	The ID of the payment that the deposit was created by
void	Boolean	If a payment is reversed, the deposit will be void
date	Date	The date and time the discount was created in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "amount_remaining": 0.00,
    "payment_id": 3,
    "void": false,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Get individual account discount

Get an individual account discount by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts/:discount_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
discount_id	Number	The ID of the discount

Success 200

Field	Type	Description
id	Number	An ID representing the individual discount
amount	Number	The amount of the discount in the system currency
amount_remaining	Number	How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount
service_id	Number	The ID of the service that the discount is associated with
date	Date	The date and time the discount was created in UTC
reversed	Boolean	If this is true, the discount has been reversed
reversed_at	Date	If reversed is true, this is the date the discount was reversed
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit
description	String	A description for the transaction, if one was set. The name of the service that generated it, otherwise.
quantity	Number	If this was a one time transaction, this is the number of applications that created this single transaction. Default value: `1`
general_ledger_code	String	The general ledger code for this transaction
general_ledger_code_description	String	The description for the general ledger code for this transaction

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 265,
    "amount": 186.48,
    "amount_remaining": 198.48,
    "service_id": 6,
    "date": "2015-09-22 03:03:17",
    "reversed": false,
    "reversed_at": null,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ],
    "description": "I wrote this",
    "quantity": 1,
    "general_ledger_code": "1000",
    "general_ledger_code_description": "test test"
  }
}

Account_Transactions - Get individual account discount

Get an individual account discount by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts/:discount_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
discount_id	Number	The ID of the discount

Success 200

Field	Type	Description
id	Number	An ID representing the individual discount
amount	Number	The amount of the discount in the system currency
amount_remaining	Number	How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount
service_id	Number	The ID of the service that the discount is associated with
date	Date	The date and time the discount was created in UTC
reversed	Boolean	If this is true, the discount has been reversed
reversed_at	Date	If reversed is true, this is the date the discount was reversed
taxes	Array	An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 265,
    "amount": 186.48,
    "amount_remaining": 198.48,
    "service_id": 6,
    "date": "2015-09-22 03:03:17",
    "reversed": false,
    "reversed_at": null,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ]
  }
}

Account_Transactions - Get individual account payment

Get an individual payment

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_id	Number	The ID of the payment

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
transaction_id	String	The transaction ID from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	If this payment is refunded/reversed, this will be true
reversed_at	Date	If a payment is refunded/reversed, this will be the date the reversal occurs
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Get individual account payment

Get an individual payment

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_id	Number	The ID of the payment

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	If this payment is refunded/reversed, this will be true
reversed_at	Date	If a payment is refunded/reversed, this will be the date the reversal occurs
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Make a one time credit card payment

Make a one time credit card payment. This does not save the credit card to Sonar.

https://example.sonar.software/api/v1/accounts/:id/transactions/one_time_credit_card_payment

Parameter

Field	Type	Description
id	Number	The ID of the account
number	Number	The credit card number
cvc optional	Number	The CVC/CVV code on the credit card. Some providers require that this is sent - if so, this is not optional.
expiration_month	Number	The month as a digit (1-12)
expiration_year	Number	The 4 digit expiration year (e.g. 2018)
amount	Number	The amount to charge the card
name_on_account	String	The name on the credit card
line1	String	Line 1 of the card address (e.g. the street address.)
city	String	The city of the card address
state	String	The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country
zip	String	The ZIP/postal code of the card address
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field	Type	Description
id	Number	The ID of the payment
transaction_id	String	The transaction ID from the payment processor
message	String	The message from the payment processor
success	Boolean	Whether or not the payment was successfully processed

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "transaction_id": "100325923924",
    "message": "Declined Sale",
    "success": false
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "That is not a valid credit card number. Please check and try again.",
     "status_code": 422
   }
 }

Account_Transactions - Make a one time credit card payment

Make a one time credit card payment. This does not save the credit card to Sonar.

https://example.sonar.software/api/v1/accounts/:id/transactions/one_time_credit_card_payment

Parameter

Field	Type	Description
id	Number	The ID of the account
number	Number	The credit card number
expiration_month	Number	The month as a digit (1-12)
expiration_year	Number	The 4 digit expiration year (e.g. 2018)
amount	Number	The amount to charge the card
name_on_account	String	The name on the credit card
line1	String	Line 1 of the card address (e.g. the street address.)
city	String	The city of the card address
state	String	The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country
zip	String	The ZIP/postal code of the card address
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field	Type	Description
id	Number	The ID of the payment
transaction_id	String	The transaction ID from the payment processor
message	String	The message from the payment processor
success	Boolean	Whether or not the payment was successfully processed

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "transaction_id": "100325923924",
    "message": "Declined Sale",
    "success": false
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "That is not a valid credit card number. Please check and try again.",
     "status_code": 422
   }
 }

Account_Transactions - Make a one time credit card payment

Make a one time credit card payment. This does not save the credit card to Sonar.

https://example.sonar.software/api/v1/accounts/:id/transactions/one_time_credit_card_payment

Parameter

Field	Type	Description
id	Number	The ID of the account
number	Number	The credit card number
expiration_month	Number	The month as a digit (1-12)
expiration_year	Number	The 4 digit expiration year (e.g. 2018)
amount	Number	The amount to charge the card

Success 200

Field	Type	Description
id	Number	The ID of the payment
transaction_id	String	The transaction ID from the payment processor
message	String	The message from the payment processor
success	Boolean	Whether or not the payment was successfully processed

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "transaction_id": "100325923924",
    "message": "Declined Sale",
    "success": false
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "That is not a valid credit card number. Please check and try again.",
     "status_code": 422
   }
 }

Account_Transactions - Refund a payment

Refund a payment. This will refund the payment transaction. You can only refund payments that are made with a payment processor, or via ACH batch. Cash, check or wire payments can only be reversed, as we have no way of refunding those payments.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id/refund

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_id	Number	The ID of the payment

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
transaction_id	String	The transaction ID from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	This will be true if the payment reversed successfully
reversed_at	Date	This will be the current date if the payment was reversed successfully
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": true,
    "reversed_at": "2015-09-30",
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Refund a payment

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id/refund

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_id	Number	The ID of the payment

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	This will be true if the payment reversed successfully
reversed_at	Date	This will be the current date if the payment was reversed successfully
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "success": true,
    "reversed": true,
    "reversed_at": "2015-09-30",
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Reverse a payment

Reverse a payment. This will reverse the payment transaction but will not issue a refund to the payment processor. Once a payment is reversed, it cannot be refunded, so ensure you use refund instead of reverse if you want the payment processor to issue a refund.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id/reverse

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_id	Number	The ID of the payment

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
transaction_id	String	The transaction ID from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	This will be true if the payment reversed successfully
reversed_at	Date	This will be the current date if the payment was reversed successfully
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": true,
    "reversed_at": "2015-09-30",
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Reverse a payment

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id/reverse

Parameter

Field	Type	Description
account_id	Number	The ID of the account
payment_id	Number	The ID of the payment

Success 200

Field	Type	Description
id	Number	An ID representing the individual payment
amount	Number	The amount of the deposit in the system currency
payment_method_id	Number	The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null
type	String	The type of payment this is Allowed values: `"credit card"`, `"echeck"`, `"ach"`, `"cash"`, `"check"`, `"wire"`, `"paypal"`
response_message	String	The response message from the payment processor, if one was used for this transaction
success	Boolean	Whether or not this payment was successful. Will only ever show false if this was run through a payment processor
reversed	Boolean	This will be true if the payment reversed successfully
reversed_at	Date	This will be the current date if the payment was reversed successfully
date	Date	The date the payment was applied

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "success": true,
    "reversed": true,
    "reversed_at": "2015-09-30",
    "date": "2015-09-23 16:55:12"
  }
}

Accounts

Accounts - Create account

Create a new account. There are items entered here such as the address and contact information that must be obtained from other endpoints. They are required here to meet the requirements with the Sonar application - a contact must have a physical address and primary contact when created.

https://example.sonar.software/api/v1/accounts

Parameter

Field	Type	Description
id optional	Number	An ID for the account. The ID must be numeric and not currently in use. If you do not include an ID (which is the recommended method) then the next available ID will be automatically used. Once this is set, it cannot be changed.
name	String	A name for the new account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups optional	Array	An array of account group IDs, this can be referenced against /system/account_groups/:id
sub_accounts optional	Array	An array of account IDs that you want to attach to this account as children
next_bill_date optional	String	A YYYY-MM-DD formatted date that dictates when the account should next bill. Generally speaking, you should allow Sonar to automatically calculate this. The only time you should set it is if this customer specifically needs to bill on a future date that would not be the calculated date - for example, if this is a customer that is billed once every 6 months and they billed 2 months ago, you would need to manually set this to 4 months in the future. Whatever day is set on your next_bill_date will also be set as the future recurring billing day. The day portion of next_bill_date cannot be higher than 28, as Sonar only allows 28 day billing
line1	String	The first line of the physical address
line2 optional	String	The second line of the physical address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country. It is important to set this correctly as it will be used for calculating geo taxes
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal.
longitude	Float	The longitude of the address, in decimal.
contact_name	String	The name of the primary account contact
role	String	The role of the primary account contact (e.g. CEO, Accountant)
email_address optional	String	The email address of the contact
phone_numbers optional	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension. See the contact section of the API for an example
email_message_categories	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

Success 200

Field	Type	Description
id	Number	The internal ID of the account
name	String	The name of the account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups	Array	An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id
balance_due	Number	The sum of all remaining_due amounts on associated invoices
balance_total	Number	The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits
sub_accounts	Array	An array of account IDs that are children/sub accounts of this account
next_bill_date	String	The date on which this account will next bill. This will be null if the account has never been activated
delinquent	Boolean	Whether or not the account is currently delinquent

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Accounts - Create account

https://example.sonar.software/api/v1/accounts

Parameter

Field	Type	Description
name	String	A name for the new account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups optional	Array	An array of account group IDs, this can be referenced against /system/account_groups/:id
sub_accounts optional	Array	An array of account IDs that you want to attach to this account as children
next_bill_date optional	String	A YYYY-MM-DD formatted date that dictates when the account should next bill. Generally speaking, you should allow Sonar to automatically calculate this. The only time you should set it is if this customer specifically needs to bill on a future date that would not be the calculated date - for example, if this is a customer that is billed once every 6 months and they billed 2 months ago, you would need to manually set this to 4 months in the future. Whatever day is set on your next_bill_date will also be set as the future recurring billing day. The day portion of next_bill_date cannot be higher than 28, as Sonar only allows 28 day billing
line1	String	The first line of the physical address
line2 optional	String	The second line of the physical address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country. It is important to set this correctly as it will be used for calculating geo taxes
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal.
longitude	Float	The longitude of the address, in decimal.
contact_name	String	The name of the primary account contact
role optional	String	The role of the primary account contact (e.g. CEO, Accountant)
email_address optional	String	The email address of the contact
phone_numbers optional	Object	An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension. See the contact section of the API for an example
email_message_categories optional	Array	An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

Success 200

Field	Type	Description
id	Number	The internal ID of the account
name	String	The name of the account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups	Array	An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id
balance_due	Number	The sum of all remaining_due amounts on associated invoices
balance_total	Number	The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits
sub_accounts	Array	An array of account IDs that are children/sub accounts of this account
next_bill_date	String	The date on which this account will next bill. This will be null if the account has never been activated
delinquent	Boolean	Whether or not the account is currently delinquent

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Accounts - Delete account

Delete an account. Be careful when using this method! This will disable the accounts services and make all the data associated with this account inaccessible as soon as it is deleted.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field	Type	Description
id	Number	The ID of the account

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "Account deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the account could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "That account does not exist",
         "status_code": 404
     }
 }

Accounts - Get all accounts

Get a list of the accounts in the system

https://example.sonar.software/api/v1/accounts

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the account
name	String	The name of the account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups	Array	An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id
balance_due	Number	The sum of all remaining_due amounts on associated invoices
balance_total	Number	The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits
sub_accounts	Array	An array of account IDs that are children/sub accounts of this account
next_bill_date	String	The date on which this account will next bill. This will be null if the account has never been activated
delinquent	Boolean	Whether or not the account is currently delinquent

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Jacob Kailing",
            "account_status_id": 1,
            "account_type_id": 1,
            "account_groups": [],
            "balance_due": 0,
            "balance_total": 0,
            "sub_accounts": [],
            "next_bill_date": "2015-10-01",
            "delinquent": false
        },
        {
            "id": 2,
            "name": "Horatio T Hornblower",
            "account_status_id": 1,
            "account_type_id": 1,
            "account_groups": [],
            "balance_due": 0,
            "balance_total": 0,
            "sub_accounts": [],
            "next_bill_date": "2015-11-03",
            "delinquent": true
        }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Accounts - Get individual account

Get an individual account.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field	Type	Description
id	Number	The ID of the account

Success 200

Field	Type	Description
id	Number	The internal ID of the account
name	String	The name of the account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups	Array	An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id
balance_due	Number	The sum of all remaining_due amounts on associated invoices
balance_total	Number	The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits
sub_accounts	Array	An array of account IDs that are children/sub accounts of this account
next_bill_date	String	The date on which this account will next bill. This will be null if the account has never been activated
delinquent	Boolean	Whether or not the account is currently delinquent

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2018-03-04",
        "delinquent": false
    }
}

Accounts - Update account

Update an account.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field	Type	Description
id	Number	The ID of the account group to update
name optional	String	The name of the account
account_type_id optional	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id optional	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups optional	Array	An array of account group IDs, this can be referenced against /system/account_groups/:id
sub_accounts optional	Array	An array of account IDs that you want to attach to this account as children. If you submit this parameter, you must submit all the IDs that should be children - if you omit existing children, they will be attached. An empty array will detach all children
prorate	Boolean	If you have account super user permissions, and you are changing the account status, set this to 'true' to prorate the change and 'false' to not prorate the change. If you do not have account superuser permissions, this value will be ignored and the system default prorating value will be used Default value: `false`
next_bill_date optional	Date	If you would like to override the next bill date to a different date, it can be updated here in YYYY-MM-DD format. You should generally not do this, as you can cause serious billing issues - this is almost always only used when importing data from another system. The day portion of next_bill_date cannot be higher than 28, as Sonar only allows 28 day billing. This requires account superuser permissions

Success 200

Field	Type	Description
id	Number	The internal ID of the account
name	String	The name of the account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups	Array	An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id
balance_due	Number	The sum of all remaining_due amounts on associated invoices
balance_total	Number	The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits
sub_accounts	Array	An array of account IDs that are children/sub accounts of this account
next_bill_date	String	The date on which this account will next bill. This will be null if the account has never been activated
delinquent	Boolean	Whether or not the account is currently delinquent

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Accounts - Update account

Update an account.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field	Type	Description
id	Number	The ID of the account group to update
name optional	String	The name of the account
account_type_id optional	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id optional	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups optional	Array	An array of account group IDs, this can be referenced against /system/account_groups/:id
sub_accounts optional	Array	An array of account IDs that you want to attach to this account as children. If you submit this parameter, you must submit all the IDs that should be children - if you omit existing children, they will be attached. An empty array will detach all children
prorate	Boolean	If you have account super user permissions, and you are changing the account status, set this to 'true' to prorate the change and 'false' to not prorate the change. If you do not have account superuser permissions, this value will be ignored and the system default prorating value will be used Default value: `false`
next_bill_date optional	Date	If you would like to override the next bill date to a different date, it can be updated here in YYYY-MM-DD format. You should generally not do this, as you can cause serious billing issues - this is almost always only used when importing data from another system. The day portion of next_bill_date cannot be higher than 28, as Sonar only allows 28 day billing. This requires account superuser permissions

Success 200

Field	Type	Description
id	Number	The internal ID of the account
name	String	The name of the account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups	Array	An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id
balance_due	Number	The sum of all remaining_due amounts on associated invoices
balance_total	Number	The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits
sub_accounts	Array	An array of account IDs that are children/sub accounts of this account
next_bill_date	String	The date on which this account will next bill. This will be null if the account has never been activated
delinquent	Boolean	Whether or not the account is currently delinquent

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Accounts - Update account

Update an account.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field	Type	Description
id	Number	The ID of the account group to update
name optional	String	The name of the account
account_type_id optional	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id optional	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups optional	Array	An array of account group IDs, this can be referenced against /system/account_groups/:id
sub_accounts optional	Array	An array of account IDs that you want to attach to this account as children. If you submit this parameter, you must submit all the IDs that should be children - if you omit existing children, they will be attached. An empty array will detach all children
prorate	Boolean	If you have account super user permissions, and you are changing the account status, set this to 'true' to prorate the change and 'false' to not prorate the change. If you do not have account superuser permissions, this value will be ignored and the system default prorating value will be used Default value: `false`

Success 200

Field	Type	Description
id	Number	The internal ID of the account
name	String	The name of the account
account_type_id	Number	An ID representing the type of account, this can be referenced against /system/account_types/:id
account_status_id	Number	An ID representing the status of the account, this can be referenced against /system/account_statuses/:id
account_groups	Array	An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id
balance_due	Number	The sum of all remaining_due amounts on associated invoices
balance_total	Number	The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits
sub_accounts	Array	An array of account IDs that are children/sub accounts of this account
next_bill_date	String	The date on which this account will next bill. This will be null if the account has never been activated
delinquent	Boolean	Whether or not the account is currently delinquent

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Address Lists

Address_Lists - Create a new address list

Create a new address list. If there are enabled, available inline devices in Sonar, this address list will be immediately created on them.

https://example.sonar.software/api/v1/network/provisioning/address_lists

Parameter

Field	Type	Description
name	String	The name of the address list
delinquent optional	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked. Default value: `3` Allowed values: `1`, `2`, `3`
active optional	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked. Default value: `3` Allowed values: `1`, `2`, `3`
account_groups optional	Array	An array of account group IDs that are a relation to this address list.
account_types optional	Array	An array of account type IDs that are a relation to this address list.
services optional	Array	An array of data service IDs that are a relation to this address list.
account_statuses optional	Array	An array of account status IDs that are a relation to this address list.
usage_based_billing_policies optional	Array	An array of usage based billing policy IDs that are checked for caps being exceeded

Success 200

Field	Type	Description
id	Number	The ID of the address list
name	String	The name of the address list
delinquent	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups	Array	An array of account group IDs that are a relation to this address list.
account_types	Array	An array of account type IDs that are a relation to this address list.
services	Array	An array of data service IDs that are a relation to this address list.
account_statuses	Array	An array of account status IDs that are a relation to this address list.
usage_based_billing_policies	Array	An array of usage based billing policy IDs that are checked for caps being exceeded

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "test",
    "delinquent": 3,
    "active": 3,
    "account_groups": [],
    "account_types": [],
    "services": [
      14,
      12
    ],
    "account_statuses": [],
    "usage_based_billing_policies": [
      6,
      5
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The address list name has already been taken.",
         },
         "status_code": 422
     }
 }

Address_Lists - Create a new address list

Create a new address list. If there are enabled, available inline devices in Sonar, this address list will be immediately created on them.

https://example.sonar.software/api/v1/network/provisioning/address_lists

Parameter

Field	Type	Description
name	String	The name of the address list
delinquent optional	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked. Default value: `3` Allowed values: `1`, `2`, `3`
active optional	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked. Default value: `3` Allowed values: `1`, `2`, `3`
account_groups optional	Array	An array of account group IDs that are a relation to this address list.
account_types optional	Array	An array of account type IDs that are a relation to this address list.
services optional	Array	An array of data service IDs that are a relation to this address list.
account_statuses optional	Array	An array of account status IDs that are a relation to this address list.

Success 200

Field	Type	Description
id	Number	The ID of the address list
name	String	The name of the address list
delinquent	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups	Array	An array of account group IDs that are a relation to this address list.
account_types	Array	An array of account type IDs that are a relation to this address list.
services	Array	An array of data service IDs that are a relation to this address list.
account_statuses	Array	An array of account status IDs that are a relation to this address list.

Success-Response:

HTTP/1.1 201 OK
{
  "id": 34,
  "name": "Boneapart",
  "delinquent": 3,
  "active": 2,
  "account_groups": [],
  "account_types": [
    1
  ],
  "services": [],
  "account_statuses": []
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The address list name has already been taken.",
         },
         "status_code": 422
     }
 }

Address_Lists - Delete address list

Delete an address list. This will immediately remove the address list from all enabled inline devices in a good status.

https://example.sonar.software/api/v1/network/provisioning/address_lists/:id

Parameter

Field	Type	Description
id	Number	The ID of the address list.

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the address list could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "Address list does not exist."
         },
         "status_code": 404
     }
 }

Address_Lists - Delete address list

Delete an address list. This will immediately remove the address list from all enabled inline devices in a good status.

https://example.sonar.software/api/v1/network/provisioning/address_lists/:id

Parameter

Field	Type	Description
id	Number	The ID of the address list.

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the address list could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "Address list does not exist."
         },
         "status_code": 404
     }
 }

Address_Lists - Get all address lists

Get a list of address lists.

https://example.sonar.software/api/v1/network/provisioning/address_lists

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the address list
name	String	The name of the address list
delinquent	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups	Array	An array of account group IDs that are a relation to this address list.
account_types	Array	An array of account type IDs that are a relation to this address list.
services	Array	An array of data service IDs that are a relation to this address list.
account_statuses	Array	An array of account status IDs that are a relation to this address list.
usage_based_billing_policies	Array	An array of usage based billing policy IDs that are checked for caps being exceeded

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "test",
      "delinquent": 3,
      "active": 3,
      "account_groups": [],
      "account_types": [],
      "services": [
        14,
        12
      ],
      "account_statuses": [],
      "usage_based_billing_policies": [
        6,
        5
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Address_Lists - Get all address lists

Get a list of address lists.

https://example.sonar.software/api/v1/network/provisioning/address_lists

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the address list
name	String	The name of the address list
delinquent	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups	Array	An array of account group IDs that are a relation to this address list.
account_types	Array	An array of account type IDs that are a relation to this address list.
services	Array	An array of data service IDs that are a relation to this address list.
account_statuses	Array	An array of account status IDs that are a relation to this address list.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
        {
         "id": 23,
         "name": "Active",
         "delinquent": 3,
         "active": 1,
         "account_groups": [],
         "account_types": [],
         "services": [],
         "account_statuses": []
       },
       {
         "id": 24,
         "name": "Inactive",
         "delinquent": 3,
         "active": 2,
         "account_groups": [],
         "account_types": [],
         "services": [],
         "account_statuses": []
       },
       {
         "id": 25,
         "name": "Delinquent",
         "delinquent": 1,
         "active": 3,
         "account_groups": [],
         "account_types": [],
         "services": [],
         "account_statuses": []
       },
       {
         "id": 20,
         "name": "MyDataService",
         "delinquent": 3,
         "active": 3,
         "account_groups": [],
         "account_types": [],
         "services": [
           1
         ],
         "account_statuses": []
       }
  ],
  "paginator": {
    "total_count": 4,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Address_Lists - Get individual address list

Get an individual address list.

https://example.sonar.software/api/v1/network/provisioning/address_lists/:id

Parameter

Field	Type	Description
id	Number	The ID of the address list

Success 200

Field	Type	Description
id	Number	The ID of the address list
name	String	The name of the address list
delinquent	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups	Array	An array of account group IDs that are a relation to this address list.
account_types	Array	An array of account type IDs that are a relation to this address list.
services	Array	An array of data service IDs that are a relation to this address list.
account_statuses	Array	An array of account status IDs that are a relation to this address list.
usage_based_billing_policies	Array	An array of usage based billing policy IDs that are checked for caps being exceeded

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "test",
    "delinquent": 3,
    "active": 3,
    "account_groups": [],
    "account_types": [],
    "services": [
      14,
      12
    ],
    "account_statuses": [],
    "usage_based_billing_policies": [
      6,
      5
    ]
  }
}

Address_Lists - Get individual address list

Get an individual address list.

https://example.sonar.software/api/v1/network/provisioning/address_lists/:id

Parameter

Field	Type	Description
id	Number	The ID of the address list

Success 200

Field	Type	Description
id	Number	The ID of the address list
name	String	The name of the address list
delinquent	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups	Array	An array of account group IDs that are a relation to this address list.
account_types	Array	An array of account type IDs that are a relation to this address list.
services	Array	An array of data service IDs that are a relation to this address list.
account_statuses	Array	An array of account status IDs that are a relation to this address list.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 23,
    "name": "Active",
    "delinquent": 3,
    "active": 1,
    "account_groups": [],
    "account_types": [],
    "services": [],
    "account_statuses": []
  }
}

Address_Lists - Update address list

Update an address list

https://example.sonar.software/api/v1/provisioning/address_lists/:id

Parameter

Field	Type	Description
id	Number	The ID of the address list
name optional	String	The name of the address list
delinquent optional	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active optional	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups optional	Array	An array of account group IDs that are a relation to this address list.
account_types optional	Array	An array of account type IDs that are a relation to this address list.
services optional	Array	An array of data service IDs that are a relation to this address list.
account_statuses optional	Array	An array of account status IDs that are a relation to this address list.
usage_based_billing_policies optional	Array	An array of usage based billing policy IDs that are checked for caps being exceeded

Success 200

Field	Type	Description
id	Number	The ID of the address list
name	String	The name of the address list
delinquent	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups	Array	An array of account group IDs that are a relation to this address list.
account_types	Array	An array of account type IDs that are a relation to this address list.
services	Array	An array of data service IDs that are a relation to this address list.
account_statuses	Array	An array of account status IDs that are a relation to this address list.
usage_based_billing	Array	policies An array of usage based billing policy IDs that are checked for caps being exceeded

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 23,
    "name": "Active",
    "delinquent": 3,
    "active": 1,
    "account_groups": [],
    "account_types": [],
    "services": [],
    "account_statuses": [],
    "usage_based_billing_policies": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Address_Lists - Update address list

Update an address list

https://example.sonar.software/api/v1/provisioning/address_lists/:id

Parameter

Field	Type	Description
id	Number	The ID of the address list
name optional	String	The name of the address list
delinquent optional	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active optional	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups optional	Array	An array of account group IDs that are a relation to this address list.
account_types optional	Array	An array of account type IDs that are a relation to this address list.
services optional	Array	An array of data service IDs that are a relation to this address list.
account_statuses optional	Array	An array of account status IDs that are a relation to this address list.

Success 200

Field	Type	Description
id	Number	The ID of the address list
name	String	The name of the address list
delinquent	Number	If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
account_groups	Array	An array of account group IDs that are a relation to this address list.
account_types	Array	An array of account type IDs that are a relation to this address list.
services	Array	An array of data service IDs that are a relation to this address list.
account_statuses	Array	An array of account status IDs that are a relation to this address list.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 23,
    "name": "Active",
    "delinquent": 3,
    "active": 1,
    "account_groups": [],
    "account_types": [],
    "services": [],
    "account_statuses": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Alerting Rotations

Alerting_Rotations - Create a new alerting rotation day/time

Create a new alerting rotation day/time.

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days

Parameter

Field	Type	Description
id	Integer	The ID of the alerting rotation
day	Integer	An integer representing the day of the week, where 0 is Sunday and 6 is Saturday Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6`
start_timestamp	Time	A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.
end_timestamp	Time	A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

Success 200

Field	Type	Description
id	Integer	The ID of the alerting rotation day/time.
day	Integer	An integer representing the day of the week, where 0 is Sunday and 6 is Saturday Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6`
start_timestamp	Time	A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.
end_timestamp	Time	A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "day": 5,
    "start_timestamp": "08:35",
    "end_timestamp": "17:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "data": {
     "id": 1,
     "day": 2,
     "start_timestamp": "8:0",
     "end_timestamp": "17:0"
   }
 }

Alerting_Rotations - Create a new alerting rotation

Create a new alerting rotation.

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations

Parameter

Field	Type	Description
enabled	Boolean	Whether or not the rotation is enabled
name	String	A name for the alerting rotation
start	Date	A date when the rotation should begin
repetitions	Integer	The number of times the rotation should repeat
weeks	Integer	How frequently the rotation should repeat, in weeks. `1` means every week, `2` means every other week, `3` means on one week, off two weeks, on one week, etc.
infinite_repetitions	Boolean	Should this rotation repeat forever? If this is `true`, `repetitions` is ignored.
warning_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a warning state before an alert is sent
down_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a down state before an alert is sent
user_ids	Array	An array of users that are in this rotation
all_accounts	Boolean	If this is `true`, then the `account_group_ids` and `account_type_ids` values are ignored, and this rotation applies to all accounts
all_network_sites	Boolean	If this is `true`, then the `network_site_ids` value is ignored, and this rotation applies to all network sites
all_inventory_models	Boolean	If this is `true`, then the `inventory_model_ids` value is ignored, and this rotation applies to all inventory models
network_site_ids	Array	An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.
inventory_model_ids	Array	An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.
account_group_ids	Array	An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.
account_type_ids	Array	An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

Success 200

Field	Type	Description
id	Integer	The ID of the alerting rotation.
enabled	Boolean	Whether or not the rotation is enabled
name	String	A name for the alerting rotation
start	Date	A date when the rotation should begin
repetitions	Integer	The number of times the rotation should repeat
weeks	Integer	How frequently the rotation should repeat, in weeks. `1` means every week, `2` means every other week, `3` means on one week, off two weeks, on one week, etc.
infinite_repetitions	Boolean	Should this rotation repeat forever? If this is `true`, `repetitions` is ignored.
warning_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a warning state before an alert is sent
down_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a down state before an alert is sent
user_ids	Array	An array of users that are in this rotation
all_accounts	Boolean	If this is `true`, then the `account_group_ids` and `account_type_ids` values are ignored, and this rotation applies to all accounts
all_network_sites	Boolean	If this is `true`, then the `network_site_ids` value is ignored, and this rotation applies to all network sites
all_inventory_models	Boolean	If this is `true`, then the `inventory_model_ids` value is ignored, and this rotation applies to all inventory models
network_site_ids	Array	An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.
inventory_model_ids	Array	An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.
account_group_ids	Array	An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.
account_type_ids	Array	An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "enabled": true,
    "name": "Rotation 1 Updated",
    "start": "2016-12-15",
    "repetitions": 5,
    "infinite_repetitions": true,
    "weeks": 1,
    "warning_time_in_minutes_before_alerting": 10,
    "down_time_in_minutes_before_alerting": 5,
    "user_ids": [
      1
    ],
    "all_accounts": true,
    "all_network_sites": true,
    "all_inventory_models": true,
    "network_site_ids": [],
    "inventory_model_ids": [
      1,
      2
    ],
    "account_group_ids": [],
    "account_type_ids": [
      2,
      1
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "start": "start must be a date in YYYY-MM-DD format."
     },
     "status_code": 422
   }
 }

Alerting_Rotations - Delete a alerting rotation day/time

Delete a alerting rotation day/time

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days/:alerting_rotation_day_id

Parameter

Field	Type	Description
id	Integer	The ID of the alerting rotation
alerting_rotation_day_id	Integer	The ID of the alerting rotation day/time

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the alerting rotation day/time could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "alerting rotation day/time does not exist.",
         "status_code": 404
     }
 }

Alerting_Rotations - Delete a alerting rotation

Delete a alerting rotation

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id

Parameter

Field	Type	Description
id	Integer	The ID of the alerting rotation

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the alerting rotation could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "alerting rotation does not exist.",
         "status_code": 404
     }
 }

Alerting_Rotations - Get all alerting rotations

Get all alerting rotations

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the alerting rotation.
enabled	Boolean	Whether or not the rotation is enabled
name	String	A name for the alerting rotation
start	Date	A date when the rotation should begin
repetitions	Integer	The number of times the rotation should repeat
weeks	Integer	How frequently the rotation should repeat, in weeks. `1` means every week, `2` means every other week, `3` means on one week, off two weeks, on one week, etc.
infinite_repetitions	Boolean	Should this rotation repeat forever? If this is `true`, `repetitions` is ignored.
warning_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a warning state before an alert is sent
down_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a down state before an alert is sent
user_ids	Array	An array of users that are in this rotation
all_accounts	Boolean	If this is `true`, then the `account_group_ids` and `account_type_ids` values are ignored, and this rotation applies to all accounts
all_network_sites	Boolean	If this is `true`, then the `network_site_ids` value is ignored, and this rotation applies to all network sites
all_inventory_models	Boolean	If this is `true`, then the `inventory_model_ids` value is ignored, and this rotation applies to all inventory models
network_site_ids	Array	An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.
inventory_model_ids	Array	An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.
account_group_ids	Array	An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.
account_type_ids	Array	An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "enabled": true,
      "name": "Rotation 1 Updated",
      "start": "2016-12-15",
      "repetitions": 5,
      "infinite_repetitions": true,
      "weeks": 1,
      "warning_time_in_minutes_before_alerting": 10,
      "down_time_in_minutes_before_alerting": 5,
      "user_ids": [
        1
      ],
      "all_accounts": true,
      "all_network_sites": true,
      "all_inventory_models": true,
      "network_site_ids": [],
      "inventory_model_ids": [
        1,
        2
      ],
      "account_group_ids": [],
      "account_type_ids": [
        2,
        1
      ]
    },
    {
      "id": 3,
      "enabled": true,
      "name": "Another Rotation",
      "start": "2016-12-15",
      "repetitions": 5,
      "infinite_repetitions": true,
      "weeks": 1,
      "warning_time_in_minutes_before_alerting": 10,
      "down_time_in_minutes_before_alerting": 5,
      "user_ids": [
        1
      ],
      "all_accounts": true,
      "all_network_sites": true,
      "all_inventory_models": true,
      "network_site_ids": [],
      "inventory_model_ids": [
        1,
        2
      ],
      "account_group_ids": [],
      "account_type_ids": [
        2,
        1
      ]
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Alerting_Rotations - Get all alerting rotation day/times

Get all alerting rotation day/times

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days

Parameter

Field	Type	Description
id	Integer	The ID of the alerting rotation
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the alerting rotation day/time.
day	Integer	An integer representing the day of the week, where 0 is Sunday and 6 is Saturday Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6`
start_timestamp	Time	A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.
end_timestamp	Time	A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "day": 2,
      "start_timestamp": "08:00",
      "end_timestamp": "17:00"
    },
    {
      "id": 2,
      "day": 2,
      "start_timestamp": "08:35",
      "end_timestamp": "17:00"
    },
    {
      "id": 3,
      "day": 5,
      "start_timestamp": "08:35",
      "end_timestamp": "17:00"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Alerting_Rotations - Get an individual alerting rotation day/time

Get an individual alerting rotation day/time

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days/:alerting_rotation_day_id

Parameter

Field	Type	Description
id	Integer	The ID of the alerting rotation
alerting_rotation_day_id	Integer	The ID of the alerting rotation day

Success 200

Field	Type	Description
id	Integer	The ID of the alerting rotation day/time.
day	Integer	An integer representing the day of the week, where 0 is Sunday and 6 is Saturday Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6`
start_timestamp	Time	A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.
end_timestamp	Time	A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "day": 2,
    "start_timestamp": "08:00",
    "end_timestamp": "17:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Alerting_Rotations - Get an individual alerting rotation

Get an individual alerting rotation

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id

Parameter

Field	Type	Description
id	Integer	The ID of the alerting rotation

Success 200

Field	Type	Description
id	Integer	The ID of the alerting rotation.
enabled	Boolean	Whether or not the rotation is enabled
name	String	A name for the alerting rotation
start	Date	A date when the rotation should begin
repetitions	Integer	The number of times the rotation should repeat
weeks	Integer	How frequently the rotation should repeat, in weeks. `1` means every week, `2` means every other week, `3` means on one week, off two weeks, on one week, etc.
infinite_repetitions	Boolean	Should this rotation repeat forever? If this is `true`, `repetitions` is ignored.
warning_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a warning state before an alert is sent
down_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a down state before an alert is sent
user_ids	Array	An array of users that are in this rotation
all_accounts	Boolean	If this is `true`, then the `account_group_ids` and `account_type_ids` values are ignored, and this rotation applies to all accounts
all_network_sites	Boolean	If this is `true`, then the `network_site_ids` value is ignored, and this rotation applies to all network sites
all_inventory_models	Boolean	If this is `true`, then the `inventory_model_ids` value is ignored, and this rotation applies to all inventory models
network_site_ids	Array	An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.
inventory_model_ids	Array	An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.
account_group_ids	Array	An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.
account_type_ids	Array	An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "enabled": true,
    "name": "Rotation 1 Updated",
    "start": "2016-12-15",
    "repetitions": 5,
    "infinite_repetitions": true,
    "weeks": 1,
    "warning_time_in_minutes_before_alerting": 10,
    "down_time_in_minutes_before_alerting": 5,
    "user_ids": [
      1
    ],
    "all_accounts": true,
    "all_network_sites": true,
    "all_inventory_models": true,
    "network_site_ids": [],
    "inventory_model_ids": [
      1,
      2
    ],
    "account_group_ids": [],
    "account_type_ids": [
      2,
      1
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Alerting_Rotations - Update alerting rotation day/time

Update an existing alerting rotation day/time.

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days/:alerting_rotation_day_id

Parameter

Field	Type	Description
id	Integer	The ID of the alerting rotation
alerting_rotation_day_id	Integer	The ID of the alerting rotation day
day	Integer	An integer representing the day of the week, where 0 is Sunday and 6 is Saturday Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6`
start_timestamp	Time	A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.
end_timestamp	Time	A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

Success 200

Field	Type	Description
id	Integer	The ID of the alerting rotation day/time.
day	Integer	An integer representing the day of the week, where 0 is Sunday and 6 is Saturday Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6`
start_timestamp	Time	A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.
end_timestamp	Time	A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "day": 5,
    "start_timestamp": "08:35",
    "end_timestamp": "17:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Alerting_Rotations - Update alerting rotation

Update an existing alerting rotation.

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id

Parameter

Field	Type	Description
id	Integer	The ID of the alerting rotation.
enabled	Boolean	Whether or not the rotation is enabled
name	String	A name for the alerting rotation
start	Date	A date when the rotation should begin
repetitions	Integer	The number of times the rotation should repeat
weeks	Integer	How frequently the rotation should repeat, in weeks. `1` means every week, `2` means every other week, `3` means on one week, off two weeks, on one week, etc.
infinite_repetitions	Boolean	Should this rotation repeat forever? If this is `true`, `repetitions` is ignored.
warning_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a warning state before an alert is sent
down_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a down state before an alert is sent
user_ids	Array	An array of users that are in this rotation
all_accounts	Boolean	If this is `true`, then the `account_group_ids` and `account_type_ids` values are ignored, and this rotation applies to all accounts
all_network_sites	Boolean	If this is `true`, then the `network_site_ids` value is ignored, and this rotation applies to all network sites
all_inventory_models	Boolean	If this is `true`, then the `inventory_model_ids` value is ignored, and this rotation applies to all inventory models
network_site_ids	Array	An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.
inventory_model_ids	Array	An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.
account_group_ids	Array	An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.
account_type_ids	Array	An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

Success 200

Field	Type	Description
id	Integer	The ID of the alerting rotation.
enabled	Boolean	Whether or not the rotation is enabled
name	String	A name for the alerting rotation
start	Date	A date when the rotation should begin
repetitions	Integer	The number of times the rotation should repeat
weeks	Integer	How frequently the rotation should repeat, in weeks. `1` means every week, `2` means every other week, `3` means on one week, off two weeks, on one week, etc.
infinite_repetitions	Boolean	Should this rotation repeat forever? If this is `true`, `repetitions` is ignored.
warning_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a warning state before an alert is sent
down_time_in_minutes_before_alerting	Integer	How long devices that this alerting rotation covers can be in a down state before an alert is sent
user_ids	Array	An array of users that are in this rotation
all_accounts	Boolean	If this is `true`, then the `account_group_ids` and `account_type_ids` values are ignored, and this rotation applies to all accounts
all_network_sites	Boolean	If this is `true`, then the `network_site_ids` value is ignored, and this rotation applies to all network sites
all_inventory_models	Boolean	If this is `true`, then the `inventory_model_ids` value is ignored, and this rotation applies to all inventory models
network_site_ids	Array	An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.
inventory_model_ids	Array	An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.
account_group_ids	Array	An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.
account_type_ids	Array	An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "enabled": true,
    "name": "Rotation 1 Updated",
    "start": "2016-12-15",
    "repetitions": 5,
    "infinite_repetitions": true,
    "weeks": 1,
    "warning_time_in_minutes_before_alerting": 10,
    "down_time_in_minutes_before_alerting": 5,
    "user_ids": [
      1
    ],
    "all_accounts": true,
    "all_network_sites": true,
    "all_inventory_models": true,
    "network_site_ids": [],
    "inventory_model_ids": [
      1,
      2
    ],
    "account_group_ids": [],
    "account_type_ids": [
      2,
      1
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

CDRs

CDRs - Submit a standardized CDR for rating

Submit call records to be rated by Sonar. The records must be in a standardized format. When submitting records to this endpoint, batch them into sets of 5,000 records at a time. At this time, only 10 digit calls are supported for national calls (NANP.) Anything longer than 10 digits will be treated as international.

https://example.sonar.software/api/v1/system/voice/cdr_rating

An example CDR

{
   "voice_provider_id": 1,
   "records": [
       {
           "origination": "1234567890",
           "destination": "0111234657364",
           "call_start": "2016-08-11 09:43:21",
           "duration": 123
       },
       {
           "origination": "1234567891",
           "destination": "18006667777",
           "call_start": "2016-08-11 09:47:21",
           "duration": 38
       }
   ]
}

Parameter

Field	Type	Description
voice_provider_id	Integer	The ID of the voice provider which these CDRs are for. This is how you specify which rate deck to use for these calls.
records	Array	An array of records, the format of which is shown in the example below, and in the entries below this one.
origination	String	The originating DID (10 digits, or 11 with a leading 1.)
destination	String	The destination DID (Minimum of 10 digits)
call_start	DateTime	The date and time the call was placed, in UTC in YYYY-MM-DD HH:mm:ss format. Hours should be in 24 hour format.
duration	Integer	The duration of the call, in seconds

Success 200

Field	Type	Description
success	Boolean	`true` if the records have been queued for rating.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Contracts

Contracts - Create a new contract

Create a new contract from a contract template. A link to sign the contract will be emailed to the specified contact, as long as the contact has an email address.

https://example.sonar.software/api/v1/accounts/:account_id/contracts

Parameter

Field	Type	Description
account_id	Integer	The ID of the account to assign the contract to
contract_template_id	Integer	The ID of a contract template
contact_id	Integer	The ID of a contact on the account specified in `account_id`. This contact will receive an email with a link to sign the contract.
custom_message optional	String	If you'd like a customized message to be displayed on the contract signature page, then enter it here.

Success 200

Field	Type	Description
id	Integer	The ID of the contract.
contract_name	String	The name of the contract
contract_text	String	The body of the contract, may contain some HTML.
contact_id	Integer	The ID of the contact associated with the contract. Only valid while the contract is unsigned.
term_in_months	Integer	The contract term in months, if it has one.
acceptance_datetime	DateTime	The date and time the contract was signed, in UTC
expiration_date	Date	The date the contract with expire, if it had a term. This is in the system timezone.
custom_message	String	The custom message associated with the contract
signer_name	String	The name the signer entered when signing the contract, if it is signed
signer_ip	String	The IP address of the party that signed the contract, if it is signed

Success-Response:

 HTTP/1.1 201 OK
 {
  "data": {
    "id": 7,
    "contract_name": "Example Contract",
    "contract_text": "Here is an example contract. Very nice.",
    "contact_id": 1,
    "term_in_months": 12,
    "acceptance_datetime": null,
    "expiration_date": null,
    "custom_message": "Hello John! Please sign this contract so we can get the ball rolling on synergizing your ability to evaluate our ground breaking product!",
    "signer_name": null,
    "signer_ip": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 4xx
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Contracts - Delete a contract

Delete a contract. Only unsigned contracts can be deleted.

https://example.sonar.software/api/v1/accounts/:account_id/contracts/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account.
id	Integer	The ID of the contract

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the contract could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Contract does not exist.",
         "status_code": 404
     }
 }

Contracts - Get all contracts

Get all contracts

https://example.sonar.software/api/v1/accounts/:account_id/contracts

Parameter

Field	Type	Description
account_id	Integer	The ID of the account you wish to return the contract list for
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the contract.
contract_name	String	The name of the contract
contract_text	String	The body of the contract, may contain some HTML.
contact_id	Integer	The ID of the contact associated with the contract. Only valid while the contract is unsigned.
term_in_months	Integer	The contract term in months, if it has one.
acceptance_datetime	DateTime	The date and time the contract was signed, in UTC
expiration_date	Date	The date the contract with expire, if it had a term. This is in the system timezone.
custom_message	String	The custom message associated with the contract
signer_name	String	The name the signer entered when signing the contract, if it is signed
signer_ip	String	The IP address of the party that signed the contract, if it is signed
unique_link_key	String	The unique key used on the Sonar contract signature page

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
     "id": 7,
     "contract_name": "Example Contract",
     "contract_text": "Here is an example contract. Very nice!",
     "contact_id": 1,
     "term_in_months": 12,
     "acceptance_datetime": null,
     "expiration_date": null,
     "custom_message": "Hello John! Please sign this contract so we can get the ball rolling on synergizing your ability to evaluate our ground breaking product!",
     "signer_name": null,
     "signer_ip": null,
     "unique_link_key": "72ULw3Kn4mAeRnLAyrhC6XFowRdIWV7UEtyEFYQrfsILwvJv588660c0e2c12"
   }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Contracts - Get an individual contract as base64

Get an individual contract as base64. This allows you to reconstruct the PDF, so you can present it in an external system (e.g. the customer portal.)

https://example.sonar.software/api/v1/accounts/:account_id/contracts/:id/base64

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
id	Integer	The ID of the contract

Success 200

Field	Type	Description
base64	String	The base64 encoded contract

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "base64": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgaGF2ZSBtYW5hZ2VkIHRvIGRlY29kZSBteSBzZWNyZXQgYmFzZTY0IGRhdGEhIFBsZWFzZSBkb24ndCBzaGFyZSB0aGUgY29udGVudHMgb2YgdGhpcyB3aXRoIGFueW9uZSAtIGl0J3MgYSBzZWNyZXQh"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Contracts - Get an individual contract

Get an individual contract

https://example.sonar.software/api/v1/accounts/:account_id/contracts/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
id	Integer	The ID of the contract

Success 200

Field	Type	Description
id	Integer	The ID of the contract.
contract_name	String	The name of the contract
contract_text	String	The body of the contract, may contain some HTML.
contact_id	Integer	The ID of the contact associated with the contract. Only valid while the contract is unsigned.
term_in_months	Integer	The contract term in months, if it has one.
acceptance_datetime	DateTime	The date and time the contract was signed, in UTC
expiration_date	Date	The date the contract with expire, if it had a term. This is in the system timezone.
custom_message	String	The custom message associated with the contract
signer_name	String	The name the signer entered when signing the contract, if it is signed
signer_ip	String	The IP address of the party that signed the contract, if it is signed
unique_link_key	String	The unique key used on the Sonar contract signature page

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 7,
     "contract_name": "Example Contract",
     "contract_text": "Here is an example contract. Very nice!",
     "contact_id": 1,
     "term_in_months": 12,
     "acceptance_datetime": null,
     "expiration_date": null,
     "custom_message": "Hello John! Please sign this contract so we can get the ball rolling on synergizing your ability to evaluate our ground breaking product!",
     "signer_name": null,
     "signer_ip": null,
     "unique_link_key": "72ULw3Kn4mAeRnLAyrhC6XFowRdIWV7UEtyEFYQrfsILwvJv588660c0e2c12"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Contracts - Update contract

Update an existing contract. The only thing that can be updated is the custom message - to make any other changes, delete and re-add.

https://example.sonar.software/api/v1/accounts/:account_id/contracts/:id

Parameter

Field	Type	Description
account_id	Integer	The account ID
id	Integer	The contract ID
custom_message	String	The custom message to display when the contract is being signed.
contact_id	Integer	The ID of the contact the contract should be emailed to. If this is changed, the contract will be emailed to the new contact.

Success 200

Field	Type	Description
id	Integer	The ID of the contract.
contract_name	String	The name of the contract
contract_text	String	The body of the contract, may contain some HTML.
contact_id	Integer	The ID of the contact associated with the contract. Only valid while the contract is unsigned.
term_in_months	Integer	The contract term in months, if it has one.
acceptance_datetime	DateTime	The date and time the contract was signed, in UTC
expiration_date	Date	The date the contract with expire, if it had a term. This is in the system timezone.
custom_message	String	The custom message associated with the contract
signer_name	String	The name the signer entered when signing the contract, if it is signed
signer_ip	String	The IP address of the party that signed the contract, if it is signed
unique_link_key	String	The unique key used on the Sonar contract signature page

Success-Response:

 HTTP/1.1 201 OK
 {
  "data": {
    "id": 7,
    "contract_name": "Example Contract",
    "contract_text": "Here is an example contract. Very nice.",
    "contact_id": 1,
    "term_in_months": 12,
    "acceptance_datetime": null,
    "expiration_date": null,
    "custom_message": "Hello John! Please sign this contract so we can get the ball rolling on synergizing your ability to evaluate our ground breaking product!",
    "signer_name": null,
    "signer_ip": null,
    "unique_link_key": "72ULw3Kn4mAeRnLAyrhC6XFowRdIWV7UEtyEFYQrfsILwvJv588660c0e2c12"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Custom Fields

Custom_Fields - Get custom fields for entity

Get a list of the custom fields assigned to this entity that have information set.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id

Parameter

Field Type Description

entity

String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site", "jobs"

entity_id

Number

The ID of the entity

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "custom_field_id": 4,
      "data": false
    },
    {
      "custom_field_id": 3,
      "data": "Some text"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Custom_Fields - Get custom fields for entity

Get a list of the custom fields assigned to this entity that have information set.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id

Parameter

Field Type Description

entity

String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site"

entity_id

Number

The ID of the entity

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "custom_field_id": 4,
      "data": false
    },
    {
      "custom_field_id": 3,
      "data": "Some text"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Custom_Fields - Get custom fields for entity

Get a list of the custom fields assigned to this entity that have information set.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id

Parameter

Field Type Description

entity

String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee"

entity_id

Number

The ID of the entity

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_name	String	The name of the custom field. You should generally use the field ID programatically, as the name can change
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "custom_field_id": 4,
      "custom_field_name": "Is The Customer Alive?",
      "data": false
    },
    {
      "custom_field_id": 3,
      "custom_field_name": "Please enter some text in this field",
      "data": "Some text"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Custom_Fields - Get custom fields for entity

Get a list of the custom fields assigned to this entity that have information set.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id

Parameter

Field Type Description

entity

String

The type of entity to get custom fields for.

Allowed values: "account"

entity_id

Number

The ID of the entity

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "custom_field_id": 4,
      "data": false
    },
    {
      "custom_field_id": 3,
      "data": "Some text"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Custom_Fields - Get individual custom field for entity

Get a specific custom field for a specific entity, by custom field ID.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description

entity

String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site", "jobs"

entity_id

Number

The ID of the entity

custom_field_id

Number

The ID of the custom field (provided at /system/custom_fields)

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 200 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Get individual custom field for entity

Get a specific custom field for a specific entity, by custom field ID.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description

entity

String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site"

entity_id

Number

The ID of the entity

custom_field_id

Number

The ID of the custom field (provided at /system/custom_fields)

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 200 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Get individual custom field for entity

Get a specific custom field for a specific entity, by custom field ID.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description

entity

String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee"

entity_id

Number

The ID of the entity

custom_field_id

Number

The ID of the custom field (provided at /system/custom_fields)

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_name	String	The name of the custom field. You should generally use the field ID programatically, as the name can change
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 200 OK
{
  "data":
    {
      "custom_field_id": 4,
      "custom_field_name": "Is The Customer A Walrus?",
      "data": false
    }
}

Custom_Fields - Get individual custom field for entity

Get a specific custom field for a specific entity, by custom field ID.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description

entity

String

The type of entity to get custom fields for.

Allowed values: "account"

entity_id

Number

The ID of the entity

custom_field_id

Number

The ID of the custom field (provided at /system/custom_fields)

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 200 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Update a custom field for an entity

Update the data in a custom field for an entity.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field	Type	Description
entity	String	The type of entity to get custom fields for. Allowed values: `"account"`, `"generic_inventory_assignee"`, `"network_site"`, `"jobs"`
entity_id	Number	The ID of the entity
custom_field_id	Number	The ID of the custom field (provided at /system/custom_fields)
data	String	The content of the custom field. If the custom field is a checkbox, this must be a boolean. If it is a select/dropdown, it must be one of the predefined fields allowed. If it is a date, it must be YYYY-MM-DD format.

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 201 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Update a custom field for an entity

Update the data in a custom field for an entity.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field	Type	Description
entity	String	The type of entity to get custom fields for. Allowed values: `"account"`, `"generic_inventory_assignee"`, `"network_site"`
entity_id	Number	The ID of the entity
custom_field_id	Number	The ID of the custom field (provided at /system/custom_fields)
data	String	The content of the custom field. If the custom field is a checkbox, this must be a boolean. If it is a select/dropdown, it must be one of the predefined fields allowed. If it is a date, it must be YYYY-MM-DD format.

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 201 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Update a custom field for an entity

Update the data in a custom field for an entity.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field	Type	Description
entity	String	The type of entity to get custom fields for. Allowed values: `"account"`, `"generic_inventory_assignee"`
entity_id	Number	The ID of the entity
custom_field_id	Number	The ID of the custom field (provided at /system/custom_fields)
data	String	The content of the custom field. If the custom field is a checkbox, this must be a boolean. If it is a select/dropdown, it must be one of the predefined fields allowed. If it is a date, it must be YYYY-MM-DD format.

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_name	String	The name of the custom field. You should generally use the field ID programatically, as the name can change
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 201 OK
{
  "data":
    {
      "custom_field_id": 4,
      "custom_field_name": "Is The Customer Partial to Pumpkin Pie?",
      "data": false
    }
}

Custom_Fields - Update a custom field for an entity

Update the data in a custom field for an entity.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field	Type	Description
entity	String	The type of entity to get custom fields for. Allowed values: `"account"`
entity_id	Number	The ID of the entity
custom_field_id	Number	The ID of the custom field (provided at /system/custom_fields)
data	String	The content of the custom field. If the custom field is a checkbox, this must be a boolean. If it is a select/dropdown, it must be one of the predefined fields allowed. If it is a date, it must be YYYY-MM-DD format.

Success 200

Field	Type	Description
data	String	The content of the custom field
custom_field_id	Number	A unique ID that matches the ID of a custom field defined at /system/custom_fields

Success-Response:

HTTP/1.1 201 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Customer Portal

Customer_Portal - Look up an email address

Look up an email address to see if it is valid. This is designed to be used for account creation, or resetting forgotten passwords. This will return the first contact found with the email address provided, that is a primary contact, and has no username associated with it. This endpoint is not throttled - you must throttle your look up function or this presents a security risk!

https://example.sonar.software/api/v1/customer_portal/email_lookup

Parameter

Field Type Description

email_address

String

The email address to look up

check_if_available

Boolean

If true, this checks if the contact is primary, and it does not have a username. If this is false, then it will check if the account is primary, and it does have a username.

Default value: true

Success 200

Field	Type	Description
email_address	String	The email address of the contact
account_id	Number	The account ID of the contact
contact_id	Number	The ID of the contact
username	String	The current username for this contact, if one exists

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "email_address": "someone@example.com",
    "account_id": 1,
    "contact_id": 1,
    "username": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "The email address was not found.",
     "status_code": 422
   }
 }

Customer_Portal - Validate credentials

Validate a contact's username and password for customer portal access. This will validate if the username and password matches, and the contact is a primary contact. You should only use this endpoint if you are building your own customer portal, and you want to hook into the username/password storage on a Sonar contact. This endpoint is not throttled - you must throttle your authentication function or this presents a security risk!

https://example.sonar.software/api/v1/customer_portal/auth

Parameter

Field	Type	Description
username	String	The case-insensitive username to use for authentication
password	Number	The case-sensitive password to use for authentication

Success 200

Field	Type	Description
contact_name	String	The name of the contact
email_address	String	The email address of the contact
account_id	Number	The account ID of the contact
contact_id	Number	The ID of the contact
username	String	The username that was authenticated

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "contact_name": "John Doe",
    "email_address": "someone@example.com",
    "account_id": 1,
    "contact_id": 1,
    "username": "testtest123"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Invalid username or password.",
     "status_code": 422
   }
 }

DHCP Server Identifiers

DHCP_Server_Identifiers - Create a new DHCP server identifier

Create a new DHCP server identifier.

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers

Parameter

Field	Type	Description
name	String	A name for the DHCP server identifier
ip_pool_ids	Array	An array of IP pool IDs that should be associated with this identifier

Success 200

Field	Type	Description
id	Integer	The ID of the DHCP server identifier.
name	String	The name of the DHCP server identifier
ip_pool_ids	Array	An array of IP pool IDs that should be associated with this identifier

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Papaya",
    "ip_pool_ids": [
       1,
       3
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

DHCP_Server_Identifiers - Delete a DHCP server identifier

Delete a DHCP server identifier

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers/:id

Parameter

Field	Type	Description
id	Integer	The ID of the DHCP server identifier

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the DHCP server identifier could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "DHCP server identifier does not exist.",
         "status_code": 404
     }
 }

DHCP_Server_Identifiers - Get all DHCP server identifiers

Get all DHCP server identifiers

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the DHCP server identifier.
name	String	The name of the DHCP server identifier
ip_pool_ids	Array	An array of IP pool IDs that should be associated with this identifier

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
      {
      "id": 2,
      "name": "Papaya",
      "ip_pool_ids": [
         1,
         3
      ]
    },
    {
      "id": 3,
      "name": "SteelBlue",
      "ip_pool_ids": [
         4,
         6,
         12
      ]
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

DHCP_Server_Identifiers - Get an individual DHCP server identifier

Get an individual DHCP server identifier

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers/:id

Parameter

Field	Type	Description
id	Integer	The ID of the DHCP server identifier

Success 200

Field	Type	Description
id	Integer	The ID of the DHCP server identifier.
name	String	The name of the DHCP server identifier
ip_pool_ids	Array	An array of IP pool IDs that should be associated with this identifier

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 3,
     "name": "SteelBlue",
     "ip_pool_ids": [
        4,
        6,
        12
     ]
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

DHCP_Server_Identifiers - Update DHCP server identifier

Update an existing DHCP server identifier.

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers/:id

Parameter

Field	Type	Description
name	String	A name for the DHCP server identifier
ip_pool_ids	Array	An array of IP pool IDs that should be associated with this identifier

Success 200

Field	Type	Description
id	Integer	The ID of the DHCP server identifier.
name	String	The name of the DHCP server identifier
ip_pool_ids	Array	An array of IP pool IDs that should be associated with this identifier

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

DHCP Servers

DHCP_Servers - Get all DHCP servers

Get a list of DHCP servers.

https://example.sonar.software/api/v1/network/provisioning/dhcp_servers

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the DHCP server
ip_address	String	The IP address of the DHCP server
name	String	The name provided for the DHCP server
type	String	The type of DHCP server that this is Allowed values: `"mikrotik"`
controls_all_pools	Boolean	If this DHCP server stores leases for all pools defined in Sonar or not
failures	Number	The number of failures writing leases that have been encountered since last rewrite/reset
device_status	Boolean	Whether or not the device is in a good status. Devices with a status of 'false' will not have leases written.
status_message	String	A message describing why the device is in a bad status, if device_status is false.
ip_pools	Array	If controls_all_pools is false, this will be an array of IP pool IDs that the server controls.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "ip_address": "192.168.1.51",
      "name": "MikroTik",
      "enabled": true,
      "type": "mikrotik",
      "controls_all_pools": true,
      "failures": 0,
      "device_status": true,
      "status_message": null,
      "ip_pools": []
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

DHCP_Servers - Get individual DHCP server

Get a single DHCP server

https://example.sonar.software/api/v1/network/provisioning/dhcp_servers/:id

Parameter

Field	Type	Description
id	Number	The ID of the DHCP server

Success 200

Field	Type	Description
id	Number	The ID of the DHCP server
ip_address	String	The IP address of the DHCP server
name	String	The name provided for the DHCP server
type	String	The type of DHCP server that this is Allowed values: `"mikrotik"`
controls_all_pools	Boolean	If this DHCP server stores leases for all pools defined in Sonar or not
failures	Number	The number of failures writing leases that have been encountered since last rewrite/reset
device_status	Boolean	Whether or not the device is in a good status. Devices with a status of 'false' will not have leases written.
status_message	String	A message describing why the device is in a bad status, if device_status is false.
ip_pools	Array	If controls_all_pools is false, this will be an array of IP pool IDs that the server controls.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "ip_address": "192.168.1.51",
    "name": "MikroTik",
    "enabled": true,
    "type": "mikrotik",
    "controls_all_pools": true,
    "failures": 0,
    "device_status": true,
    "status_message": null,
    "ip_pools": []
  }
}

DIDs

DIDs - Delete a DID

Delete a DID

https://example.sonar.software/api/v1/system/voice/dids/:id

Parameter

Field	Type	Description
id	Number	The ID of the DID

Success 200

Field	Type	Description
success	Boolean	Will be `true` if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the DID could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "DID does not exist.",
         "status_code": 404
     }
 }

DIDs - Get all DIDs

Get all DIDs

https://example.sonar.software/api/v1/system/voice/dids

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the DID.
did	String	The DID
account_id	Integer	The account ID the DID is assigned to
service_id	Integer	The ID of the voice service the DID is associated with
rate_center_id	Integer	The ID of the rate center the DID is assigned to

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
     "id": 7,
     "did": "1234567892",
     "account_id": null,
     "service_id": null,
     "rate_center_id": 1
   },
   {
     "id": 8,
     "did": "1234567893",
     "account_id": null,
     "service_id": null,
     "rate_center_id": 1
   },
   {
     "id": 9,
     "did": "1111112022",
     "account_id": null,
     "service_id": null,
     "rate_center_id": 1
   }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

DIDs - Get an individual DID

Get an individual DID

https://example.sonar.software/api/v1/system/voice/dids/:id

Parameter

Field	Type	Description
id	Number	The ID of the DID

Success 200

Field	Type	Description
id	Number	The ID of the DID.
did	String	The DID
account_id	Integer	The account ID the DID is assigned to
service_id	Integer	The ID of the voice service the DID is associated with
rate_center_id	Integer	The ID of the rate center the DID is assigned to

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 8,
    "did": "1234567893",
    "account_id": null,
    "service_id": null,
    "rate_center_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

DIDs - Mass add DIDs

This endpoint allows you to import a large quantity of DIDs at once. This is used to add new, available DIDs to Sonar. When importing very large quantities of DIDs, split them into batches and import 5000 at a time. Sonar currently only supports 10 digit DIDs.

https://example.sonar.software/api/v1/system/voice/dids

Example usage:


{
  "dids": [
      "1234567890",
      "0987654321"
  ],
  "rate_center_id": 1
}

Parameter

Field	Type	Description
dids	Array	An array of ten digit DIDs
rate_center_id	Integer	The ID of the rate center to add these DIDs to

Success 200

Field	Type	Description
success	Boolean	Will be `true` if the DIDs were successfully added.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Your submission contains duplicate DIDs. All DIDs must be unique."
     "status_code": 422
   }
 }

Data

Data - Email categories

Get a list of email categories. These are used when setting email category preferences on contacts. This returns an array of objects.

https://example.sonar.software/api/v1/_data/email_categories

Success 200

Field	Type	Description
id	Number	The ID of the email category
name	String	A name (localized to the system language) that describes the category

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Financial"
    },
    {
      "id": 3,
      "name": "General"
    },
    {
      "id": 4,
      "name": "Service Related"
    },
    {
      "id": 5,
      "name": "Outage Notifications"
    }
  ]
}

Data - Get Sonar version

Get the version of this Sonar instance.

https://example.sonar.software/api/v1/_data/version

Success 200

Field	Type	Description
version	String	The software version of Sonar.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "version": "1.2.38"
  }
}

Data - Supported counties

Get a list of counties for a US state. These are mainly used when configuring geotaxes.

https://example.sonar.software/api/v1/_data/counties/:subdivision

Parameter

Field	Type	Description
subdivision	String	A US subdivision string obtained from /_data/subdivisions/US

Success 200

Field	Type	Description
data	Array	An array containing all counties for that state.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    "Adams Co.",
    "Ashland Co.",
    "Barron Co.",
    "Bayfield Co.",
    "Brown Co.",
    "Buffalo Co.",
    "Burnett Co.",
    "Calumet Co.",
    "Chippewa Co.",
    "Clark Co.",
    "Columbia Co.",
    "Crawford Co.",
    "Dane Co.",
    "Dodge Co.",
    "Door Co.",
    "Douglas Co.",
    "Dunn Co.",
    "Eau Claire Co.",
    "Florence Co.",
    "Fond du Lac Co.",
    "Forest Co.",
    "Grant Co.",
    "Green Co.",
    "Green Lake Co.",
    "Iowa Co.",
    "Iron Co.",
    "Jackson Co.",
    "Jefferson Co.",
    "Juneau Co.",
    "Kenosha Co.",
    "Kewaunee Co.",
    "La Crosse Co.",
    "Lafayette Co.",
    "Langlade Co.",
    "Lincoln Co.",
    "Manitowoc Co.",
    "Marathon Co.",
    "Marinette Co.",
    "Marquette Co.",
    "Menominee Co.",
    "Milwaukee Co.",
    "Monroe Co.",
    "Oconto Co.",
    "Oneida Co.",
    "Outagamie Co.",
    "Ozaukee Co.",
    "Pepin Co.",
    "Pierce Co.",
    "Polk Co.",
    "Portage Co.",
    "Price Co.",
    "Racine Co.",
    "Richland Co.",
    "Rock Co.",
    "Rusk Co.",
    "St. Croix Co.",
    "Sauk Co.",
    "Sawyer Co.",
    "Shawano Co.",
    "Sheboygan Co.",
    "Taylor Co.",
    "Trempealeau Co.",
    "Vernon Co.",
    "Vilas Co.",
    "Walworth Co.",
    "Washburn Co.",
    "Washington Co.",
    "Waukesha Co.",
    "Waupaca Co.",
    "Waushara Co.",
    "Winnebago Co.",
    "Wood Co."
  ]
}

Data - Supported countries

Get a list of supported countries. The object property is the correct value to use when setting a country on an entity. The value is the name of the country.

https://example.sonar.software/api/v1/_data/countries

Success 200

Field	Type	Description
data	Object	An object containing all supported countries.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "US": "United States",
       "CA": "Canada",
       "AF": "Afghanistan",
       "AL": "Albania",
       "DZ": "Algeria",
       "AS": "American Samoa",
       //etc etc
   }
}

Data - Supported locales

Get a list of supported locales.

https://example.sonar.software/api/v1/_data/locales

Success 200

Field	Type	Description
data	Object	An object containing all supported locales

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "en": "English (US)",
       "es": "Español",
       "fr": "Français"
       }
   }
}

Data - Supported subdivisions

Get a list of supported subdivisions. A subdivision is a geographical area within a country - for example, subdivisions in the USA are states, in Canada they are provinces. The :country parameter should be a country code returned from /_data/countries.

https://example.sonar.software/api/v1/_data/subdivisions/:country

Parameter

Field	Type	Description
country	String	A two character country code obtained from /_data/countries

Success 200

Field	Type	Description
data	Object	An object containing all supported subdivisions for the country.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "Alabama": "Alabama",
    "Alaska": "Alaska",
    "American Samoa": "American Samoa",
    "Arizona": "Arizona",
    "Arkansas": "Arkansas",
    "California": "California",
    "Colorado": "Colorado",
    "Connecticut": "Connecticut",
    "Delaware": "Delaware",
    "District of Columbia": "District of Columbia",
    "Florida": "Florida",
    "Georgia": "Georgia",
    "Guam": "Guam",
    "Hawaii": "Hawaii",
    "Idaho": "Idaho",
    "Illinois": "Illinois",
    "Indiana": "Indiana",
    "Iowa": "Iowa",
    "Kansas": "Kansas",
    "Kentucky": "Kentucky",
    "Louisiana": "Louisiana",
    "Maine": "Maine",
    "Maryland": "Maryland",
    "Massachusetts": "Massachusetts",
    "Michigan": "Michigan",
    "Minnesota": "Minnesota",
    "Mississippi": "Mississippi",
    "Missouri": "Missouri",
    "Montana": "Montana",
    "Nebraska": "Nebraska",
    "Nevada": "Nevada",
    "New Hampshire": "New Hampshire",
    "New Jersey": "New Jersey",
    "New Mexico": "New Mexico",
    "New York": "New York",
    "North Carolina": "North Carolina",
    "North Dakota": "North Dakota",
    "Northern Mariana Islands": "Northern Mariana Islands",
    "Ohio": "Ohio",
    "Oklahoma": "Oklahoma",
    "Oregon": "Oregon",
    "Pennsylvania": "Pennsylvania",
    "Puerto Rico": "Puerto Rico",
    "Rhode Island": "Rhode Island",
    "South Carolina": "South Carolina",
    "South Dakota": "South Dakota",
    "Tennessee": "Tennessee",
    "Texas": "Texas",
    "United States Minor Outlying Islands": "United States Minor Outlying Islands",
    "Utah": "Utah",
    "Vermont": "Vermont",
    "Virgin Islands, U.S.": "Virgin Islands, U.S.",
    "Virginia": "Virginia",
    "Washington": "Washington",
    "West Virginia": "West Virginia",
    "Wisconsin": "Wisconsin",
    "Wyoming": "Wyoming"
  }
}

Data - Supported timezones

Get a list of supported timezones. The object property is the correct value to use when setting a timezone. The value is the translated string representing the timezone in the locale of the application.

https://example.sonar.software/api/v1/_data/timezones

Success 200

Field	Type	Description
data	Object	An object containing all supported timezones.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "Africa/Abidjan": "Africa/Abidjan",
       "Africa/Accra": "Africa/Accra",
       "Africa/Addis_Ababa": "Africa/Addis_Ababa",
       "Africa/Algiers": "Africa/Algiers",
       "Africa/Asmara": "Africa/Asmara",
       "Africa/Bamako": "Africa/Bamako",
       "Africa/Bangui": "Africa/Bangui",
       "Africa/Banjul": "Africa/Banjul",
       "Africa/Bissau": "Africa/Bissau",
       "Africa/Blantyre": "Africa/Blantyre",
       "Africa/Brazzaville": "Africa/Brazzaville",
       //etc etc
   }
}

Data - Validate an address

Validate an address for proper entry into Sonar. All addresses that you plan to enter should be run through this function.

https://example.sonar.software/api/v1/_data/validate_address

Parameter

Field	Type	Description
line1	String	The first address line (e.g. 123 Main St)
city	String	The city (e.g. London)
state	String	The state/province/subdivision (e.g. Texas)
country	String	A 2 character ISO country code (e.g. US, GB, FR, DE)

Success 200

Field	Type	Description
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
county	String	The county, for US addresses
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "line1": "615 N 6th St",
    "city": "Sheboygan",
    "state": "WI",
    "county": "Sheboygan Co.",
    "country": "US",
    "zip": "53081",
    "latitude": 43.750915527344,
    "longitude": -87.708717346191
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "The address could not be validated."
         "status_code": 422
     }
 }

Files

Files - Delete file

Delete a file. Only entities that support files can be input to this endpoint. To get a valid entity name, use the portion of the route that corresponds to the entity in another API call - for example, the entity for an account is 'accounts', for ticket replies, it is 'ticket_replies'.

https://example.sonar.software/api/v1/:entity/:entity_id/files/:file_id

Parameter

Field	Type	Description
entity_id	Number	The ID of the entity
entity	String	The type of entity (e.g. accounts, ticket_replies)
file_id	Number	The ID of the file

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the file could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "File does not exist.",
         "status_code": 404
     }
 }

Files - Get all files

Get a list of files available on a specific entity. Only entities that support files can be input to this endpoint. To get a valid entity name, use the portion of the route that corresponds to the entity in another API call - for example, the entity for an account is 'accounts', for ticket replies, it is 'ticket_replies'.

https://example.sonar.software/api/v1/:entity/:id/files

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the entity
entity	String	The type of entity

Success 200

Field	Type	Description
id	Number	The internal id of the file
filename	String	The original filename
size_in_bytes	Number	The size of the file in bytes
description	String	The description entered for the file when it was uploaded
mime_type	String	The MIME type of the file
uploader	String	The username of the user that uploaded the file

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "filename": "HC04364756.pdf",
      "size_in_bytes": 76414,
      "description": "This is a contract!",
      "mime_type": "application/pdf",
      "uploader": "admin"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Files - Get individual file

Get an individual file. This will return the file details and the base64 data which can be decoded to create the file itself. Only entities that support files can be input to this endpoint. To get a valid entity name, use the portion of the route that corresponds to the entity in another API call - for example, the entity for an account is 'accounts', for ticket replies, it is 'ticket_replies'.

https://example.sonar.software/api/v1/:entity/:entity_id/files/:file_id

Parameter

Field	Type	Description
entity_id	Number	The ID of the entity
entity	String	The type of entity (e.g. accounts, ticket_replies)
file_id	Number	The ID of the file

Success 200

Field	Type	Description
id	Number	The internal id of the file
filename	String	The original filename
size_in_bytes	Number	The size of the file in bytes
description	String	The description entered for the file when it was uploaded
mime_type	String	The MIME type of the file
uploader	String	The username of the user that uploaded the file
base64_data	String	The base64 data for the file

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 2,
      "filename": "my eighty ninth file upload.txt",
      "size_in_bytes": 19,
      "description": "This is a small file!",
      "mime_type": "text/plain",
      "uploader": "admin",
      "base64_data": "U29uYXIgaXMgdGhlIGJlc3QhCg=="
    }
}

Files - Update file details

Update details on a file. You can only change the description or the filename. To change file contents, delete it and upload a new one.

https://example.sonar.software/api/v1/:entity/:entity_id/files/:file_id

Parameter

Field	Type	Description
entity_id	Number	The ID of the entity
entity	String	The name of the entity (e.g. accounts, ticket_replies)
file_id	Number	The ID of the file
description optional	String	A description for the file
filename optional	String	A filename for the file (with extension) - e.g. myfile.pdf, myfile.png

Success 200

Field	Type	Description
id	Number	The internal id of the file
filename	String	The original filename
size_in_bytes	Number	The size of the file in bytes
description	String	The description entered for the file when it was uploaded
mime_type	String	The MIME type of the file
uploader	String	The username of the user that uploaded the file
base64_data	String	The base64 data for the file

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
      "filename": "HC04364756.pdf",
      "size_in_bytes": 76414,
      "description": "This is a contract!",
      "mime_type": "application/pdf",
      "uploader": "admin"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "file": "File ID not found."
         },
         "status_code": 422
     }
 }

Files - Upload a new file

Upload a new file to the entity. Images uploaded will be automatically converted to JPEG format and resized to a max of 2048x2048.

https://example.sonar.software/api/v1/:entity/:id/files

Parameter

Field	Type	Description
entity	String	The name of the entity (e.g. accounts, ticket_replies)
id	Number	The ID of the entity
description optional	String	A description for the file
base64_data	String	The file, base64 encoded
filename	String	A filename for the file (with extension) - e.g. myfile.pdf, myfile.png

Success 200

Field	Type	Description
id	Number	The internal id of the file
filename	String	The original filename
size_in_bytes	Number	The size of the file in bytes
description	String	The description entered for the file when it was uploaded
mime_type	String	The MIME type of the file
uploader	String	The username of the user that uploaded the file

Success-Response:

HTTP/1.1 201 OK
{
    "data":
    {
      "id": 2,
      "filename": "my first file upload.pdf",
      "size_in_bytes": 489384,
      "description": "This is a contract also!",
      "mime_type": "application/pdf",
      "uploader": "admin"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Financial

Financial - Create geotax

Create a new geographical tax. You must specify at least one geographical variable for automatic assignment to accounts based on address.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes

Parameter

Field	Type	Description
id	Number	The ID of the tax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.
zip optional	String	A valid ZIP/postal code
zip_partial_match optional	Boolean	Whether or not this geotax supports partial matching on a ZIP Default value: `false`

Success 200

Field	Type	Description
id	Number	The ID of the geotax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.
zip optional	String	A valid ZIP/postal code
zip_partial_match	Boolean	Whether or not this geotax supports partial matching on a ZIP

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Sheboygan County",
    "rate": "0.4",
    "subdivision": "Wisconsin",
    "city": null,
    "county": "Sheboygan Co.",
    "zip": null,
    "zip_partial_match": false
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Sheboygan Co. is not a valid county for the subdivision New York",
     "status_code": 422
   }
 }

Financial - Create geotax

Create a new geographical tax. You must specify at least one geographical variable for automatic assignment to accounts based on address.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes

Parameter

Field	Type	Description
id	Number	The ID of the tax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip optional	String	A valid ZIP/postal code

Success 200

Field	Type	Description
id	Number	The ID of the geotax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip optional	String	A valid ZIP/postal code

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Sheboygan County",
    "rate": "0.4",
    "subdivision": "Wisconsin",
    "city": null,
    "county": "Sheboygan Co.",
    "zip": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Sheboygan Co. is not a valid county for the subdivision New York",
     "status_code": 422
   }
 }

Financial - Create tax

Create a new tax.

https://example.sonar.software/api/v1/financial/taxes

Parameter

Field	Type	Description
name	String	A descriptive name for the tax
application	String	Either flat or percentage Allowed values: `"flat"`, `"percentage"`
type	String	Either global or geo(graphical) Allowed values: `"global"`, `"geo"`
rate	Number	The tax rate, a currency amount for flat and a percentage for percentage based taxes.

Success 200

Field	Type	Description
id	Number	The ID of the tax
name	String	A descriptive name for the tax
application	String	Either flat or percentage Allowed values: `"flat"`, `"percentage"`
type	String	Either global or geo(graphical) Allowed values: `"global"`, `"geo"`
rate	Number	The tax rate, a currency amount for flat and a percentage for percentage based taxes.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "name": "VAT",
    "application": "percentage",
    "type": "global",
    "rate": "20"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Financial - Delete geotax

Delete a tax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field	Type	Description
id	Number	The ID of the tax
geotaxid	Number	The ID of the geotax

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the geotax could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Geotax not found",
         "status_code": 404
     }
 }

Financial - Delete tax

Delete a tax.

https://example.sonar.software/api/v1/financial/taxes/:id

Parameter

Field	Type	Description
id	Number	The ID of the tax

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "Tax deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the tax could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Tax not found",
         "status_code": 404
     }
 }

Financial - Delete geotax

Delete a tax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field	Type	Description
id	Number	The ID of the tax
geotaxid	Number	The ID of the geotax

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the geotax could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Geotax not found",
         "status_code": 404
     }
 }

Financial - Get all geotaxes for a tax

Get a list of all the geographic area taxes configured for a geographical tax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes

Parameter

Field	Type	Description
id	Number	The ID of the tax
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the geotax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision	String	A valid subdivision obtained from /_data/subdivisions
city	String	A valid city
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.
zip	String	A valid ZIP/postal code
zip_partial_match	Boolean	Whether or not this geotax supports partial matching on a ZIP

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Milwaukee County",
      "rate": "0.4",
      "subdivision": "Wisconsin",
      "city": "",
      "county": "Milwaukee Co.",
      "zip": "",
      "zip_partial_match": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Financial - Get all geotaxes for a tax

Get a list of all the geographic area taxes configured for a geographical tax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes

Parameter

Field	Type	Description
id	Number	The ID of the tax
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the geotax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip optional	String	A valid ZIP/postal code

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Milwaukee County",
      "rate": "0.4",
      "subdivision": "Wisconsin",
      "city": "",
      "county": "Milwaukee Co.",
      "zip": ""
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Financial - Get all taxes

Get a list of all configured taxes.

https://example.sonar.software/api/v1/financial/taxes

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the tax
name	String	A descriptive name for the tax
application	String	Either flat or percentage Allowed values: `"flat"`, `"percentage"`
type	String	Either global or geo(graphical) Allowed values: `"global"`, `"geo"`
rate	Number	The tax rate, a currency amount for flat and a percentage for percentage based taxes.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": [
    {
      "id": 1,
      "name": "$9 Flat Tax",
      "application": "flat",
      "type": "global",
      "rate": "9"
    },
    {
      "id": 2,
      "name": "3% Tax Rate",
      "application": "percentage",
      "type": "global",
      "rate": "3"
    },
    {
      "id": 3,
      "name": "Some other tax",
      "application": "flat",
      "type": "global",
      "rate": "2"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Financial - Get individual geo tax

Get an individual geotax from a parent tax

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field	Type	Description
id	Number	The ID of the tax
geotaxid	Number	The ID of the geotax

Success 200

Field	Type	Description
id	Number	The ID of the geotax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision	String	A valid subdivision obtained from /_data/subdivisions
city	String	A valid city
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.
zip	String	A valid ZIP/postal code
zip_partial_match	Boolean	Whether or not this geotax supports partial matching on a ZIP

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Milwaukee County",
    "rate": "0.4",
    "subdivision": "Wisconsin",
    "city": "",
    "county": "Milwaukee Co.",
    "zip": "",
    "zip_partial_match": false
  }
}

Financial - Get individual geo tax

Get an individual geotax from a parent tax

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field	Type	Description
id	Number	The ID of the tax
geotaxid	Number	The ID of the geotax

Success 200

Field	Type	Description
id	Number	The ID of the geotax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip optional	String	A valid ZIP/postal code

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Milwaukee County",
    "rate": "0.4",
    "subdivision": "Wisconsin",
    "city": "",
    "county": "Milwaukee Co.",
    "zip": ""
  }
}

Financial - Get individual tax

Get an individual tax

https://example.sonar.software/api/v1/financial/taxes/:id

Parameter

Field	Type	Description
id	Number	The ID of the tax

Success 200

Field	Type	Description
id	Number	The ID of the tax
name	String	A descriptive name for the tax
application	String	Either flat or percentage Allowed values: `"flat"`, `"percentage"`
type	String	Either global or geo(graphical) Allowed values: `"global"`, `"geo"`
rate	Number	The tax rate, a currency amount for flat and a percentage for percentage based taxes.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "$9 Flat Tax",
    "application": "flat",
    "type": "global",
    "rate": "9"
  }
}

Financial - Update geotax

Update a geotax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field	Type	Description
id	Number	The ID of the tax
geotaxid	Number	The ID of the geotax.
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.
zip optional	String	A valid ZIP/postal code
zip_partial_match optional	Boolean	Whether or not this geotax supports partial matching on a ZIP

Success 200

Field	Type	Description
id	Number	The ID of the geotax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision	String	A valid subdivision obtained from /_data/subdivisions
city	String	A valid city
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.
zip	String	A valid ZIP/postal code
zip_partial_match	Boolean	Whether or not this geotax supports partial matching on a ZIP

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Sheboygan County",
    "rate": "1.0",
    "subdivision": "Wisconsin",
    "city": null,
    "county": "Sheboygan Co.",
    "zip": "12345",
    "zip_partial_match": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Sheboygan Co. is not a valid county for the subdivision New York",
     "status_code": 422
   }
 }

Financial - Update geotax

Update a geotax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field	Type	Description
id	Number	The ID of the tax
geotaxid	Number	The ID of the geotax.
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip optional	String	A valid ZIP/postal code

Success 200

Field	Type	Description
id	Number	The ID of the geotax
name	String	A descriptive name for the geotax
rate	Number	The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.
subdivision optional	String	A valid subdivision obtained from /_data/subdivisions
city optional	String	A valid city
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip optional	String	A valid ZIP/postal code

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Sheboygan County",
    "rate": "1.0",
    "subdivision": "Wisconsin",
    "city": null,
    "county": "Sheboygan Co.",
    "zip": "12345"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Sheboygan Co. is not a valid county for the subdivision New York",
     "status_code": 422
   }
 }

Financial - Update tax

Update a tax.

https://example.sonar.software/api/v1/financial/taxes/:id

Parameter

Field	Type	Description
id	Number	The ID of the tax
name	String	A descriptive name for the tax
application	String	Either flat or percentage Allowed values: `"flat"`, `"percentage"`
type	String	Either global or geo(graphical) Allowed values: `"global"`, `"geo"`
rate	Number	The tax rate, a currency amount for flat and a percentage for percentage based taxes.

Success 200

Field	Type	Description
id	Number	The ID of the tax
name	String	A descriptive name for the tax
application	String	Either flat or percentage Allowed values: `"flat"`, `"percentage"`
type	String	Either global or geo(graphical) Allowed values: `"global"`, `"geo"`
rate	Number	The tax rate, a currency amount for flat and a percentage for percentage based taxes.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "VAT",
    "application": "percentage",
    "type": "global",
    "rate": "21"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

General Ledger Codes

General_Ledger_Codes - Create a new general ledger code

Create a new general ledger code.

https://example.sonar.software/api/v1/financial/general_ledger_codes

Parameter

Field	Type	Description
code	String	A code for the general ledger code
description	String	A description for the general ledger code

Success 200

Field	Type	Description
id	Number	The ID of the general ledger code.
code	String	A code for the general ledger code
description	String	A description for the general ledger code

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "code": "12345",
    "description": "Internet Access"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "code "The code must be unique."
     },
     "status_code": 422
   }
 }

General_Ledger_Codes - Delete a general ledger code

Delete a general ledger code

https://example.sonar.software/api/v1/financial/general_ledger_codes/:id

Parameter

Field	Type	Description
id	Number	The ID of the general ledger code

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the general ledger code could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "general ledger code does not exist.",
         "status_code": 404
     }
 }

General_Ledger_Codes - Get all general ledger codes

Get all general ledger codes

https://example.sonar.software/api/v1/financial/general_ledger_codes

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the general ledger code.
code	String	A code for the general ledger code
description	String	A description for the general ledger code

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "code": "1000",
      "description": "test test"
    },
    {
      "id": 3,
      "code": "2010",
      "description": "test test test!"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

General_Ledger_Codes - Get an individual general ledger code

Get an individual general ledger code

https://example.sonar.software/api/v1/financial/general_ledger_codes/:id

Parameter

Field	Type	Description
id	Number	The ID of the general ledger code

Success 200

Field	Type	Description
id	Number	The ID of the general ledger code.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 4,
    "code": "12345",
    "description": "Internet Access"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

General_Ledger_Codes - Update general ledger code

Update an existing general ledger code.

https://example.sonar.software/api/v1/financial/general_ledger_codes/:id

Parameter

Field	Type	Description
id	Number	The general ledger code ID
code optional	String	A code for the general ledger code
description optional	String	A description for the general ledger code

Success 200

Field	Type	Description
id	Number	The ID of the general ledger code.
code	String	A code for the general ledger code
description	String	A description for the general ledger code

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "code": "123456",
    "description": "Internet Access"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "code": "The code has already been taken."
     },
     "status_code": 422
   }
 }

IPAM

Lookup an individual IP address

https://example.sonar.software/api/v1/network/ipam/ip_lookup?ip=:ip

Parameter

Field	Type	Description
ip	String	The IP address to lookup. Can be an IPv4/IPv6 address or subnet.

Success 200

Field	Type	Description
existing_assignment	Object	If this IP is currently assigned to an entity, the details will be contained within this object. Example below.
historical_assignments	Array	If this IP was previously assigned to other entities, this array will contain objects detailing who and when. Example below.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "existing_assignment": {
      "subnet": "10.0.0.2",
      "account_id": 48,
      "soft": false,
      "subnet_name": "10.0.0.0/8",
      "ip_pool_name": "Test",
      "account_name": "West Allis Prep School"
    },
    "historical_assignments": [
      {
        "subnet": "10.0.0.2",
        "removed_datetime": "2017-02-04 15:57:22",
        "assigned_datetime": "2017-02-04 15:54:06",
        "soft": false,
        "name": "Jim Patient",
        "account_id": 1,
        "from": "Feb 4, 2017 09:54:06",
        "to": "Feb 4, 2017 09:57:22"
      }
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

IPAM - Create a new IP pool

Create a new IP pool. IP pools can only be created in IPv4 subnets.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools

Parameter

Field	Type	Description
supernet_id	Integer	The ID of the supernet
subnet_id	Integer	The ID of the subnet
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any IDs included here that have 'control_all_pools' set to true will cause the call to fail.
dhcp_server_identifier_id	Integer	The ID of a DHCP server identifier to use for this pool. Set to `null` to use no identifier.

Success 200

Field	Type	Description
id	Integer	The internal id of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.
dhcp_server_identifier_id	Integer	The DHCP server identifier used for this pool. Will be `null` if unset.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.21",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
     ],
     "dhcp_server_identifier_id": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "The pool does not fit within the subnet.",
     "status_code": 422
   }
 }

IPAM - Create a new IP pool

Create a new IP pool. IP pools can only be created in IPv4 subnets.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools

Parameter

Field	Type	Description
supernet_id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any IDs included here that have 'control_all_pools' set to true will cause the call to fail.

Success 200

Field	Type	Description
id	Number	The internal id of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.21",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
      ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "The pool does not fit within the subnet.",
     "status_code": 422
   }
 }

IPAM - Create a new subnet

Create a new subnet. A subnet is a subdivided piece of a supernet, and can be used to assign IPs to various entities within Sonar, or used to build pools.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets

Parameter

Field	Type	Description
name	String	A descriptive name for the subnet.
subnet	String	The network address and CIDR prefix (e.g. 10.0.0.0/8)
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site that this subnet is deployed from.
inline_devices optional	Array	An array of inline device IDs that should provide controls for this subnet. You can only submit IDs here for inline devices that do not have the 'Controls all subnets' value enabled.
poller_id optional	Number	The ID of the poller responsible for this subnet

Success 200

Field	Type	Description
id	Number	The internal id of the subnet
name	String	A descriptive name for the subnet
subnet	String	The subnet network address and CIDR prefix.
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site this subnet is associated with.
supernet_id	Number	The ID of the supernet that this subnet is contained in.
inline_devices	Array	A list of inline device IDs that control this subnet.
poller_id	Number	The ID of the poller responsible for this subnet

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet!",
    "subnet": "192.168.100.0/27",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": [
       1
    ],
    "poller_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Your submission overlaps subnet My first Subnet!.",
     "status_code": 422
   }
 }

IPAM - Create a new subnet

Create a new subnet. A subnet is a subdivided piece of a supernet, and can be used to assign IPs to various entities within Sonar, or used to build pools.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets

Parameter

Field	Type	Description
name	String	A descriptive name for the subnet.
subnet	String	The network address and CIDR prefix (e.g. 10.0.0.0/8)
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site that this subnet is deployed from.
inline_devices optional	Array	An array of inline device IDs that should provide controls for this subnet. You can only submit IDs here for inline devices that do not have the 'Controls all subnets' value enabled.

Success 200

Field	Type	Description
id	Number	The internal id of the subnet
name	String	A descriptive name for the subnet
subnet	String	The subnet network address and CIDR prefix.
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site this subnet is associated with.
supernet_id	Number	The ID of the supernet that this subnet is contained in.
inline_devices	Array	A list of inline device IDs that control this subnet.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet!",
    "subnet": "192.168.100.0/27",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": [
       1
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Your submission overlaps subnet My first Subnet!.",
     "status_code": 422
   }
 }

IPAM - Create a new supernet

Create a new supernet. A supernet is a top level subnet (all of your defined subnets are contained within a supernet.) For example, if you want to define the subnet 10.0.0.0/24 to use in your network, you would want to define a supernet at least as large as that in order to contain it.

https://example.sonar.software/api/v1/network/ipam/supernets

Parameter

Field	Type	Description
name	String	A descriptive name for the supernet
subnet	String	The network address and CIDR prefix (e.g. 10.0.0.0/8)

Success 200

Field	Type	Description
id	Number	The internal id of the supernet
name	String	A descriptive name for the supernet
subnet	String	The supernet network address and CIDR prefix.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 6,
    "name": "My second SUPERNET!",
    "subnet": "172.16.0.0/23"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "Your submission overlaps supernet My first SUPERNET!.",
     "status_code": 422
   }
 }

IPAM - Delete IP pool

Delete an IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field	Type	Description
supernet_id	Integer	The ID of the supernet
subnet_id	Integer	The ID of the subnet
ip_pool_id	Integer	The ID of the IP pool

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the IP pool could not be deleted
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "You cannot delete a pool that contains IP assignments."
         },
         "status_code": 422
     }
 }

IPAM - Delete IP pool

Delete an IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field	Type	Description
supernet_id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet
ip_pool_id	Number	The ID of the IP pool

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the IP pool could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "You cannot delete a pool that contains IP assignments."
         },
         "status_code": 422
     }
 }

IPAM - Delete subnet

Delete a subnet. You cannot delete a subnet that has any IP pools or IP assignments associated with it, the relations must be deleted first.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets/:subnet_id

Parameter

Field	Type	Description
id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the subnet could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "This subnet cannot be deleted as it has IP pools associated with it."
         },
         "status_code": 422
     }
 }

IPAM - Delete supernet

Delete a supernet. You cannot delete a supernet that has any subnets associated with it, the subnets must be deleted first.

https://example.sonar.software/api/v1/network/ipam/supernets/:id

Parameter

Field	Type	Description
id	Number	The ID of the supernet

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the supernet could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "Supernet cannot be deleted as it contains subnets."
         },
         "status_code": 422
     }
 }

IPAM - Get all IP pools

Get a list of IP pools contained within a subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools

Parameter

Field	Type	Description
supernet_id	Integer	The ID of the supernet
subnet_id	Integer	The ID of the subnet
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The internal id of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.
dhcp_server_identifier_id	Integer	The DHCP server identifier used for this pool. Will be `null` if unset.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My first IP Pool",
      "start": "192.168.100.10",
      "end": "192.168.100.200",
      "dhcp_servers": [
           1,
           2
      ],
      "dhcp_server_identifier_id": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get all IP pools

Get a list of IP pools contained within a subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools

Parameter

Field	Type	Description
supernet_id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My first IP Pool",
      "start": "192.168.100.10",
      "end": "192.168.100.200",
      "dhcp_servers": [
           1,
           2
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get all subnets

Get a list of subnets contained within a supernet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets

Parameter

Field	Type	Description
id	Number	The ID of the supernet
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the subnet
name	String	A descriptive name for the subnet
subnet	String	The subnet network address and CIDR prefix.
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site this subnet is associated with.
supernet_id	Number	The ID of the supernet that this subnet is contained in.
inline_devices	Array	A list of inline device IDs that control this subnet.
poller_id	Number	The ID of the poller responsible for this subnet

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My first Subnet!",
      "subnet": "192.168.100.0/27",
      "type": "customer",
      "network_site_id": 1,
      "supernet_id": 4,
      "inline_devices": [
           1
       ],
       "poller_id": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get all subnets

Get a list of subnets contained within a supernet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets

Parameter

Field	Type	Description
id	Number	The ID of the supernet
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the subnet
name	String	A descriptive name for the subnet
subnet	String	The subnet network address and CIDR prefix.
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site this subnet is associated with.
supernet_id	Number	The ID of the supernet that this subnet is contained in.
inline_devices	Array	A list of inline device IDs that control this subnet.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My first Subnet!",
      "subnet": "192.168.100.0/27",
      "type": "customer",
      "network_site_id": 1,
      "supernet_id": 4,
      "inline_devices": [
           1
       ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get all supernets

Get a list of supernets. A supernet is a top level subnet (all of your defined subnets are contained within a supernet.) For example, if you want to define the subnet 10.0.0.0/24 to use in your network, you would want to define a supernet at least as large as that in order to contain it.

https://example.sonar.software/api/v1/network/ipam/supernets

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the supernet
name	String	A descriptive name for the supernet
subnet	String	The supernet network address and CIDR prefix.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 4,
      "name": "My first IPv6 Supernet!",
      "subnet": "2001::/48"
    },
    {
      "id": 5,
      "name": "My Second Supernet",
      "subnet": "10.0.0.0/8"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get individual IP pool

Get an individual IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field	Type	Description
supernet_id	Integer	The ID of the supernet
subnet_id	Integer	The ID of the subnet
ip_pool_id	Integer	The ID of the IP pool

Success 200

Field	Type	Description
id	Integer	The internal id of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.
dhcp_server_identifier_id	Integer	The DHCP server identifier used for this pool. Will be `null` if unset.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.21",
    "end": "192.168.100.25",
    "dhcp_servers": [
       1,
       2
     ],
     "dhcp_server_identifier_id": 1
  }
}

IPAM - Get individual IP pool

Get an individual IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnet/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field	Type	Description
supernet_id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet
ip_pool_id	Number	The ID of the IP pool

Success 200

Field	Type	Description
id	Number	The internal id of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.21",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
      ]
  }
}

IPAM - Get individual subnet

Get an individual subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets/:subnet_id

Parameter

Field	Type	Description
id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet

Success 200

Field	Type	Description
id	Number	The internal id of the subnet
name	String	A descriptive name for the subnet
subnet	String	The subnet network address and CIDR prefix.
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site this subnet is associated with.
supernet_id	Number	The ID of the supernet that this subnet is contained in.
inline_devices	Array	A list of inline device IDs that control this subnet.
poller_id	Number	The ID of the poller responsible for this subnet

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet!",
    "subnet": "192.168.100.0/27",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": [],
    "poller_id": 12
  }
}

IPAM - Get individual subnet

Get an individual subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnet/:subnet_id

Parameter

Field	Type	Description
id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet

Success 200

Field	Type	Description
id	Number	The internal id of the subnet
name	String	A descriptive name for the subnet
subnet	String	The subnet network address and CIDR prefix.
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site this subnet is associated with.
supernet_id	Number	The ID of the supernet that this subnet is contained in.
inline_devices	Array	A list of inline device IDs that control this subnet.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet!",
    "subnet": "192.168.100.0/27",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": []
  }
}

IPAM - Get individual supernet

Get an individual supernet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id

Parameter

Field	Type	Description
id	Number	The ID of the supernet

Success 200

Field	Type	Description
id	Number	The internal id of the supernet
name	String	A descriptive name for the supernet
subnet	String	The supernet network address and CIDR prefix.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My Second Supernet",
    "subnet": "10.0.0.0/8"
  }
}

IPAM - Update IP pool

Update an IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field	Type	Description
supernet_id	Integer	The ID of the supernet
subnet_id	Integer	The ID of the subnet
ip_pool_id	Integer	The ID of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any IDs included here that have 'control_all_pools' set to true will cause the call to fail.
dhcp_server_identifier_id	Integer	The ID of a DHCP server identifier to use for this pool. Set to `null` to use no identifier.

Success 200

Field	Type	Description
id	Integer	The internal id of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.
dhcp_server_identifier_id	Integer	The DHCP server identifier used for this pool. Will be `null` if unset.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.24",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
     ],
     "dhcp_server_identifier_id": 4
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Pool cannot be set to dynamic, as there are existing assignments in the space this pool is attempting to occupy."
         },
         "status_code": 422
     }
 }

IPAM - Update IP pool

Update an IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field	Type	Description
supernet_id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet
ip_pool_id	Number	The ID of the IP pool
name optional	String	A descriptive name for the IP pool
start optional	String	The starting IP for the IP pool
end optional	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any IDs included here that have 'control_all_pools' set to true will cause the call to fail.

Success 200

Field	Type	Description
id	Number	The internal id of the IP pool
name	String	A descriptive name for the IP pool
start	String	The starting IP for the IP pool
end	String	The ending IP for the IP pool
dhcp_servers	Array	An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.24",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
      ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Pool cannot be set to dynamic, as there are existing assignments in the space this pool is attempting to occupy."
         },
         "status_code": 422
     }
 }

IPAM - Update a dynamic IP assignment

This endpoint is deprecated and should not be used. Please visit https://github.com/sonarsoftware/dhcp_batcher for information on our new dynamic DHCP tool.

This can be submitted as either a GET or a POST, to accomodate different hardware. The sole intent of this endpoint is to tie in an external IP assignment system (e.g. a third party DHCP server) so that it can notify Sonar of lease assignment and expiration. Sonar will then use this data to perform actions such as updating an address list on a gateway device. Using this as a GET may cause issues with things like submitting JSON for the 'reference' attribute unless you implement URL encoding - using POST is always recommended if possible! An example of an automated script that can be used on a Mikrotik to deliver leases to Sonar is below.

#Set your Sonar information directly below
:global username "admin"
:global password "sonar"
:global url "192.168.1.23"

:if ($leaseBound = 0) do={ /tool fetch url="https://$url/api/v1/network/ipam/dynamic_ip_assignment?ip_address=$leaseActIP&mac_address=$leaseActMAC&expired=1" mode=https keep-result=no user=$username password=$password } else={ /tool fetch url="https://$url/api/v1/network/ipam/dynamic_ip_assignment?ip_address=$leaseActIP&mac_address=$leaseActMAC&expired=0" mode=https keep-result=no user=$username password=$password }

The criteria checked when an assignment is incoming is as follows.

Does a pool exist that this IP fits into?
Is this IP already assigned as a static assignment?
Does the MAC address exist as a MAC field on a piece of inventory assigned to an account?

If any of these checks are false, then the IP assignment will not be stored.

https://example.sonar.software/api/v1/network/ipam/dynamic_ip_assignment

Parameter

Field	Type	Description
expired optional	Boolean	If this submission is notify that is a lease is expiring, set this to true. Default value: `false`
ip_address	String	The IP address that is being assigned. You can also submit this as a subnet with a CIDR prefix if this is a larger assignment. While this will accept both IPv4 and IPv6, you would need some external method of figuring out a link between the IPv6 address and a MAC for association within Sonar, so this is likely to be difficult.
mac_address	String	The MAC address this IP is assigned to, in XX:XX:XX:XX:XX:XX format. The MAC submitted here should be the MAC you want Sonar to search for in order to find a match, so this does not necessarily need to be the 'real' MAC, but could instead be the MAC of the CPE or something similar.
reference optional	String	If you would like to store additional information about this assignment for display in Sonar, submit it here as JSON. Sonar will parse the JSON to use for later display. For example, if you wanted to submit the hostname for the reservation, send something like { "Hostname": "Alex's Laptop" }

Success 200

Field	Type	Description
account_id	Number	The ID of the account that this is linked to. Will be null if no match was found.
ip_address	String	The IP address that is being assigned.
assigned_time	String	The time the lease was assigned in UTC.
expired_time	String	The time the lease expired in UTC, will be null if it is still active.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "account_id": 5,
    "ip_address": "192.168.100.12",
    "assigned_time": "2016-01-01 12:34:45",
    "expired_time": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "ip_address": "Invalid IP address."
         },
         "status_code": 422
     }
 }

IPAM - Update subnet

Update a subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets/:subnet_id

Parameter

Field	Type	Description
id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet
name optional	String	A descriptive name for the subnet.
subnet optional	String	The network address and CIDR prefix (e.g. 10.0.0.0/8)
type optional	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id optional	Number	The ID of the network site that this subnet is deployed from.
inline_devices optional	Array	An array of inline device IDs that should provide controls for this subnet. You can only submit IDs here for inline devices that do not have the 'Controls all subnets' value enabled.
poller_id optional	Number	The ID of the poller responsible for this subnet

Success 200

Field	Type	Description
id	Number	The internal id of the subnet
name	String	A descriptive name for the subnet
subnet	String	The subnet network address and CIDR prefix.
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site this subnet is associated with.
supernet_id	Number	The ID of the supernet that this subnet is contained in.
inline_devices	Array	A list of inline device IDs that control this subnet.
poller_id	Number	The ID of the poller responsible for this subnet

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet Redux",
    "subnet": "192.168.100.0/28",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": [],
    "poller_id": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Your new subnet is too small to contain all existing IP pools linked to this subnet."
         },
         "status_code": 422
     }
 }

IPAM - Update subnet

Update a subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets/:subnet_id

Parameter

Field	Type	Description
id	Number	The ID of the supernet
subnet_id	Number	The ID of the subnet
name optional	String	A descriptive name for the subnet.
subnet optional	String	The network address and CIDR prefix (e.g. 10.0.0.0/8)
type optional	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id optional	Number	The ID of the network site that this subnet is deployed from.
inline_devices optional	Array	An array of inline device IDs that should provide controls for this subnet. You can only submit IDs here for inline devices that do not have the 'Controls all subnets' value enabled.

Success 200

Field	Type	Description
id	Number	The internal id of the subnet
name	String	A descriptive name for the subnet
subnet	String	The subnet network address and CIDR prefix.
type	String	The type of subnet this is. Allowed values: `"customer"`, `"infrastructure"`, `"reserved"`, `"mixed"`
network_site_id	Number	The ID of the network site this subnet is associated with.
supernet_id	Number	The ID of the supernet that this subnet is contained in.
inline_devices	Array	A list of inline device IDs that control this subnet.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet Redux",
    "subnet": "192.168.100.0/28",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Your new subnet is too small to contain all existing IP pools linked to this subnet."
         },
         "status_code": 422
     }
 }

IPAM - Update supernet

Update a supernet

https://example.sonar.software/api/v1/network/ipam/supernets/:id

Parameter

Field	Type	Description
id	Number	The ID of the supernet
name	String	The name of the supernet
subnet	String	The supernet network address and CIDR prefix.

Success 200

Field	Type	Description
id	Number	The internal id of the supernet
name optional	String	A descriptive name for the supernet
subnet optional	String	The supernet network address and CIDR prefix.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My Second Supernet",
    "subnet": "10.0.0.0/8"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Your new subnet is too small to contain all existing subnets linked to this supernet."
         },
         "status_code": 422
     }
 }

Inbound Email Accounts

Inbound_Email_Accounts - Create a new inbound email account

Create a new inbound email account.

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts

Parameter

Field	Type	Description
name	String	A descriptive name for the inbound email account
reply_address	String	The email address that emails sent using this account will be sent from, and wil have as a reply to address.
reply_name	String	The name that emails sent using this account will be sent from.
enabled optional	Boolean	Whether the account is enabled. Disabled accounts will not accept inbound email. Default value: `true`
user_id optional	Number	The ID of a user that will be the responsible user for tickets created using this inbound route. You must set either a user ID or a ticket group ID.
ticket_group_id optional	Number	The ID of a ticket group that tickets created using this inbound route should be placed into. You must set either a user ID or a ticket group ID.
priority optional	Number	The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low Default value: `4` Allowed values: `1`, `2`, `3`, `4`
reply optional	String	The automatic reply to emails sent to this inbound route. Can use some basic HTML.
signature optional	String	The signature appended to emails sent using this account. One variable is allowed in the signature which is `[PUBLIC_NAME]`, this variable will be replaced with the user's public name.
automatic_spam_filtering optional	Boolean	Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin. Default value: `false`
minimum_spam_score optional	Number	The minimum spam score for an inbound email to be considered spam. Default value: `5`
days_before_spam_deletion optional	Number	The number of days for spam to remain in the spam folder before being automatically deleted. Default value: `30`
slack_enabled optional	Boolean	Enable Slack.com integration Default value: `false`
slack_webhook_url optional	String	The Slack webhook URL to use for Slack integration, required if slack_enabled is true

Success 200

Field	Type	Description
id	Number	The ID of the inbound email account.
name	String	A descriptive name for the inbound email account
reply_address	String	The email address that emails sent using this account will be sent from, and wil have as a reply to address.
reply_name	String	The name that emails sent using this account will be sent from.
mailbox	String	The mailbox at sonarticketing.rocks that you should forward email to in order for it to be delivered to Sonar.
enabled	Boolean	Whether the account is enabled. Disabled accounts will not accept inbound email.
user_id	Number	The ID of a user that will be the responsible user for tickets created using this inbound route.
ticket_group_id	Number	The ID of a ticket group that tickets created using this inbound route should be placed into.
priority	Number	The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low Allowed values: `1`, `2`, `3`, `4`
reply	String	The automatic reply to emails sent to this inbound route. Can use some basic HTML.
signature	String	The signature appended to emails sent using this account. One variable is allowed in the signature which is `[PUBLIC_NAME]`, this variable will be replaced with the user's public name.
automatic_spam_filtering	Boolean	Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.
minimum_spam_score	Number	The minimum spam score for an inbound email to be considered spam.
days_before_spam_deletion	Number	The number of days for spam to remain in the spam folder before being automatically deleted.
slack_enabled optional	Boolean	Slack.com integration status
slack_webhook_url optional	String	The Slack webhook URL to use for Slack integration

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "name": "Technical Support Tier 3",
    "reply_address": "support@sonar.software",
    "reply_name": "Charles Darwin",
    "mailbox": "another_example_ok@sonarticketing.rocks",
    "enabled": true,
    "user_id": 1,
    "ticket_group_id": null,
    "priority": 4,
    "reply": null,
    "signature": null,
    "automatic_spam_filtering": false,
    "minimum_spam_score": 12,
    "days_before_spam_deletion": 60,
    "slack_enabled": false,
    "slack_webhook_url": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Inbound_Email_Accounts - Delete an inbound email account

Delete a inbound email account

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts/:id

Parameter

Field	Type	Description
id	Number	The ID of the inbound email account

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the inbound email account could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Inbound email account does not exist.",
         "status_code": 404
     }
 }

Inbound_Email_Accounts - Get all inbound email accounts

Get all inbound email accounts

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the inbound email account.
name	String	A descriptive name for the inbound email account
reply_address	String	The email address that emails sent using this account will be sent from, and wil have as a reply to address.
reply_name	String	The name that emails sent using this account will be sent from.
mailbox	String	The mailbox at sonarticketing.rocks that you should forward email to in order for it to be delivered to Sonar.
enabled	Boolean	Whether the account is enabled. Disabled accounts will not accept inbound email.
user_id	Number	The ID of a user that will be the responsible user for tickets created using this inbound route.
ticket_group_id	Number	The ID of a ticket group that tickets created using this inbound route should be placed into.
priority	Number	The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low Allowed values: `1`, `2`, `3`, `4`
reply	String	The automatic reply to emails sent to this inbound route. Can use some basic HTML.
signature	String	The signature appended to emails sent using this account. One variable is allowed in the signature which is `[PUBLIC_NAME]`, this variable will be replaced with the user's public name.
automatic_spam_filtering	Boolean	Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.
minimum_spam_score	Number	The minimum spam score for an inbound email to be considered spam.
days_before_spam_deletion	Number	The number of days for spam to remain in the spam folder before being automatically deleted.
slack_enabled optional	Boolean	Slack.com integration status
slack_webhook_url optional	String	The Slack webhook URL to use for Slack integration

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Sales",
      "reply_address": "sales@sonar.software",
      "reply_name": "Sonar",
      "mailbox": "example@sonarticketing.rocks",
      "enabled": true,
      "user_id": null,
      "ticket_group_id": null,
      "priority": 4,
      "reply": "Thanks for emailing us, pal!
",
      "signature": null,
      "automatic_spam_filtering": false,
      "minimum_spam_score": 12,
      "days_before_spam_deletion": 60,
      "slack_enabled": false,
      "slack_webhook_url": null
    },
    {
      "id": 3,
      "name": "Test with reply",
      "reply_address": "simon-test@sonar.software",
      "reply_name": "Sir Chumley",
      "mailbox": "another_example@sonarticketing.rocks",
      "enabled": true,
      "user_id": null,
      "ticket_group_id": 4,
      "priority": 2,
      "reply": "This is my reply if you don't like it, you can always replace it!",
      "signature": "[PUBLIC_NAME]
Kings of the jungle.",
      "automatic_spam_filtering": false,
      "minimum_spam_score": 12,
      "days_before_spam_deletion": 60,
      "slack_enabled": false,
      "slack_webhook_url": null
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inbound_Email_Accounts - Get an individual inbound email account

Get an individual inbound email account

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts/:id

Parameter

Field	Type	Description
id	Number	The ID of the inbound email account

Success 200

Field	Type	Description
id	Number	The ID of the inbound email account.
name	String	A descriptive name for the inbound email account
reply_address	String	The email address that emails sent using this account will be sent from, and wil have as a reply to address.
reply_name	String	The name that emails sent using this account will be sent from.
mailbox	String	The mailbox at sonarticketing.rocks that you should forward email to in order for it to be delivered to Sonar.
enabled	Boolean	Whether the account is enabled. Disabled accounts will not accept inbound email.
user_id	Number	The ID of a user that will be the responsible user for tickets created using this inbound route.
ticket_group_id	Number	The ID of a ticket group that tickets created using this inbound route should be placed into.
priority	Number	The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low Allowed values: `1`, `2`, `3`, `4`
reply	String	The automatic reply to emails sent to this inbound route. Can use some basic HTML.
signature	String	The signature appended to emails sent using this account. One variable is allowed in the signature which is `[PUBLIC_NAME]`, this variable will be replaced with the user's public name.
automatic_spam_filtering	Boolean	Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.
minimum_spam_score	Number	The minimum spam score for an inbound email to be considered spam.
days_before_spam_deletion	Number	The number of days for spam to remain in the spam folder before being automatically deleted.
slack_enabled optional	Boolean	Slack.com integration status
slack_webhook_url optional	String	The Slack webhook URL to use for Slack integration

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Sales",
    "reply_address": "sales@sonar.software",
    "reply_name": "Sonar",
    "mailbox": "example@sonarticketing.rocks",
    "enabled": true,
    "user_id": null,
    "ticket_group_id": null,
    "priority": 4,
    "reply": null,
    "signature": null,
    "automatic_spam_filtering": false,
    "minimum_spam_score": 12,
    "days_before_spam_deletion": 60,
    "slack_enabled": false,
    "slack_webhook_url": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Inbound_Email_Accounts - Update inbound email account

Update an existing inbound email account.

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts/:id

Parameter

Field	Type	Description
id	Number	The inbound email account ID
name optional	String	A descriptive name for the inbound email account
reply_address optional	String	The email address that emails sent using this account will be sent from, and wil have as a reply to address.
reply_name optional	String	The name that emails sent using this account will be sent from.
enabled optional	Boolean	Whether the account is enabled. Disabled accounts will not accept inbound email.
user_id optional	Number	The ID of a user that will be the responsible user for tickets created using this inbound route. You must set either a user ID or a ticket group ID.
ticket_group_id optional	Number	The ID of a ticket group that tickets created using this inbound route should be placed into. You must set either a user ID or a ticket group ID.
priority optional	Number	The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low Allowed values: `1`, `2`, `3`, `4`
reply optional	String	The automatic reply to emails sent to this inbound route. Can use some basic HTML.
signature optional	String	The signature appended to emails sent using this account. One variable is allowed in the signature which is `[PUBLIC_NAME]`, this variable will be replaced with the user's public name.
automatic_spam_filtering optional	Boolean	Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin. Default value: `false`
minimum_spam_score optional	Number	The minimum spam score for an inbound email to be considered spam. Default value: `5`
days_before_spam_deletion optional	Number	The number of days for spam to remain in the spam folder before being automatically deleted. Default value: `30`
slack_enabled optional	Boolean	Enable Slack.com integration
slack_webhook_url optional	String	The Slack webhook URL to use for Slack integration, required if slack_enabled is true

Success 200

Field	Type	Description
id	Number	The ID of the inbound email account.
name	String	A descriptive name for the inbound email account
reply_address	String	The email address that emails sent using this account will be sent from, and wil have as a reply to address.
reply_name	String	The name that emails sent using this account will be sent from.
mailbox	String	The mailbox at sonarticketing.rocks that you should forward email to in order for it to be delivered to Sonar.
enabled	Boolean	Whether the account is enabled. Disabled accounts will not accept inbound email.
user_id	Number	The ID of a user that will be the responsible user for tickets created using this inbound route.
ticket_group_id	Number	The ID of a ticket group that tickets created using this inbound route should be placed into.
priority	Number	The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low Allowed values: `1`, `2`, `3`, `4`
reply	String	The automatic reply to emails sent to this inbound route. Can use some basic HTML.
signature	String	The signature appended to emails sent using this account. One variable is allowed in the signature which is `[PUBLIC_NAME]`, this variable will be replaced with the user's public name.
automatic_spam_filtering	Boolean	Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.
minimum_spam_score	Number	The minimum spam score for an inbound email to be considered spam.
days_before_spam_deletion	Number	The number of days for spam to remain in the spam folder before being automatically deleted.
slack_enabled optional	Boolean	Slack.com integration status
slack_webhook_url optional	String	The Slack webhook URL to use for Slack integration

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Technical Support Tier 1000",
    "reply_address": "sales@sonar.software",
    "reply_name": "Sonar",
    "mailbox": "some_real_good_example@sonarticketing.rocks",
    "enabled": true,
    "user_id": 2,
    "ticket_group_id": null,
    "priority": 4,
    "reply": null,
    "signature": null,
    "automatic_spam_filtering": false,
    "minimum_spam_score": 12,
    "days_before_spam_deletion": 60,
    "slack_enabled": false,
    "slack_webhook_url": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Inline Devices

Inline_Devices - Get all inline devices

Get a list of inline devices.

https://example.sonar.software/api/v1/network/provisioning/inline_devices

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the inline device
name	String	The name provided for the inline device
ip_address	String	The IP address of the inline device
type	String	The type of inline device that this is Allowed values: `"mikrotik"`, `"proceraPacketLogic"`
all_subnets	Boolean	If this inline device writes address list entries for every subnet in Sonar, this will be true
enabled	Boolean	If this is false, no address list entries will be written
device_status	Boolean	Whether or not the device is in a good status. Devices with a status of 'false' will not have address list entries written.
status_message	String	A message describing why the device is in a bad status, if device_status is false.
failures	Number	The number of failures writing address list entries that have been encountered since last rewrite/reset
subnets	Array	If all_subnets is false, this will be an array of subnet ID that the device writes address list entries for.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "My Awesome RB2011",
      "type": "mikrotik",
      "ip_address": "192.168.1.51",
      "all_subnets": true,
      "enabled": true,
      "device_status": true,
      "status_message": false,
      "failures": 4,
      "subnets": []
    },
    {
      "id": 1,
      "name": "7810",
      "type": "proceraPacketLogic",
      "ip_address": "192.168.1.240",
      "all_subnets": true,
      "enabled": true,
      "device_status": true,
      "status_message": false,
      "failures": 2,
      "subnets": []
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inline_Devices - Get individual inline device

Get a single inline device

https://example.sonar.software/api/v1/network/provisioning/inline_devices/:id

Parameter

Field	Type	Description
id	Number	The ID of the inline device

Success 200

Field	Type	Description
id	Number	The ID of the inline device
name	String	The name provided for the inline device
ip_address	String	The IP address of the inline device
type	String	The type of inline device that this is Allowed values: `"mikrotik"`, `"proceraPacketLogic"`
all_subnets	Boolean	If this inline device writes address list entries for every subnet in Sonar, this will be true
enabled	Boolean	If this is false, no address list entries will be written
device_status	Boolean	Whether or not the device is in a good status. Devices with a status of 'false' will not have address list entries written.
status_message	String	A message describing why the device is in a bad status, if device_status is false.
failures	Number	The number of failures writing address list entries that have been encountered since last rewrite/reset
subnets	Array	If all_subnets is false, this will be an array of subnet ID that the device writes address list entries for.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "7810",
    "type": "proceraPacketLogic",
    "ip_address": "192.168.1.240",
    "all_subnets": true,
    "enabled": true,
    "device_status": true,
    "status_message": false,
    "failures": 2,
    "subnets": []
  }
}

Inventory Assignees

Inventory_Assignees - Create a new generic inventory assignee

Create a new generic inventory assignee.

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees

Parameter

Field	Type	Description
name	String	A unique name for the assignee
notes optional	String	Some notes to describe the assignee

Success 200

Field	Type	Description
id	Number	The internal id of the manufacturer
name	String	The name of the manufacturer
notes	String	Some notes to describe the assignee

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Mike's House of Installs",
    "notes": "If you give routers to Mike, put them here!"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Create a new location

Create a new physical inventory location.

https://example.sonar.software/api/v1/inventory/inventory_locations

Parameter

Field	Type	Description
name	String	A unique name for the location

Success 200

Field	Type	Description
id	Number	The internal id of the location
name	String	The name of the location

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "name": "Warehouse 4A-B6-234"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Create a new vehicle

Create a new vehicle. Vehicles are a type of location inventory can be stored in.

https://example.sonar.software/api/v1/inventory/vehicles

Parameter

Field	Type	Description
name	String	The unique name of the vehicle
manufacturer optional	String	The vehicle manufacturer
model optional	String	The vehicle model
year optional	Number	The year the vehicle was constructed
license_plate optional	String	The license plate/number plate of the vehicle
vin optional	String	The VIN (vehicle identification number) of the vehicle

Success 200

Field	Type	Description
id	Number	The internal id of the vehicle
name	String	The name of the vehicle
manufacturer	String	The vehicle manufacturer
model	String	The vehicle model
year	Number	The year the vehicle was constructed
license_plate	String	The license plate/number plate of the vehicle
vin	String	The VIN (vehicle identification number) of the vehicle

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
          "id": 1,
          "name": "Bob's Work Van",
          "manufacturer": "Fjord",
          "model": "G150",
          "year": 2014,
          "license_plate": "ABC123",
          "vin": "1231231234"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Delete generic inventory assignee

Delete a generic inventory assignee

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees/:id

Parameter

Field	Type	Description
id	Number	The ID of the generic inventory assignee

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the generic inventory assignee could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Assignee cannot be deleted as inventory items are stored in it.",
         "status_code": 422
     }
 }

Inventory_Assignees - Delete location

Delete an inventory location

https://example.sonar.software/api/v1/inventory/inventory_locations/:id

Parameter

Field	Type	Description
id	Number	The ID of the location

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the location could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Location cannot be deleted as inventory items are stored in it.",
         "status_code": 422
     }
 }

Inventory_Assignees - Delete vehicle

Delete a vehicle

https://example.sonar.software/api/v1/inventory/vehicles/:id

Parameter

Field	Type	Description
id	Number	The ID of the vehicle

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the vehicle could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Vehicle cannot be deleted as inventory items are stored in it.",
         "status_code": 422
     }
 }

Inventory_Assignees - Get all generic inventory assignees

Get a list of generic inventory assignees. A generic inventory assignee is used when nothing else matches - for example, you may use this to assign inventory to contractors.

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the manufacturer
name	String	The name of the manufacturer
notes	String	Some notes to describe the assignee

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Jim's Sloppy Contracting Service",
      "notes": "This is the place to assign inventory that we give to this contractor!"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Assignees - Get all locations

Get a list of physical locations that inventory items can be stored at.

https://example.sonar.software/api/v1/inventory/inventory_locations

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the location
name	String	The name of the location

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
            "id": 35,
            "name": "Benjamin's Big Red Barn"
       },
       {
           "id": 36,
           "name": "Main Warehouse"
       }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Assignees - Get all vehicles

Get a list of vehicles. Vehicles are a type of location inventory can be stored in.

https://example.sonar.software/api/v1/inventory/vehicles

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the vehicle
name	String	The name of the vehicle
manufacturer	String	The vehicle manufacturer
model	String	The vehicle model
year	Number	The year the vehicle was constructed
license_plate	String	The license plate/number plate of the vehicle
vin	String	The VIN (vehicle identification number) of the vehicle

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Bob's Work Van",
      "manufacturer": "Fjord",
      "model": "G150",
      "year": 2014,
      "license_plate": "ABC123",
      "vin": "1231231234"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Assignees - Get individual generic inventory assignee

Get an individual generic assignee.

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees/:id

Parameter

Field	Type	Description
id	Number	The ID of the assignee

Success 200

Field	Type	Description
id	Number	The internal id of the manufacturer
name	String	The name of the manufacturer
notes	String	Some notes to describe the assignee

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Mike's House of Installs",
    "notes": "If you give routers to Mike, put them here!"
  }
}

Inventory_Assignees - Get individual location

Get an individual physical inventory location.

https://example.sonar.software/api/v1/inventory/inventory_locations/:id

Parameter

Field	Type	Description
id	Number	The ID of the location

Success 200

Field	Type	Description
id	Number	The internal id of the location
name	String	The name of the location

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "Warehouse"
   }
}

Inventory_Assignees - Get individual vehicle

Get an individual vehicle.

https://example.sonar.software/api/v1/inventory/vehicles/:id

Parameter

Field	Type	Description
id	Number	The ID of the vehicle

Success 200

Field	Type	Description
id	Number	The internal id of the vehicle
name	String	The name of the vehicle
manufacturer	String	The vehicle manufacturer
model	String	The vehicle model
year	Number	The year the vehicle was constructed
license_plate	String	The license plate/number plate of the vehicle
vin	String	The VIN (vehicle identification number) of the vehicle

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
        "id": 1,
        "name": "Bob's Work Van",
        "manufacturer": "Fjord",
        "model": "G150",
        "year": 2014,
        "license_plate": "ABC123",
        "vin": "1231231234"
  }
}

Inventory_Assignees - Update generic inventory assignee

Update a generic inventory assignee.

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees/:id

Parameter

Field	Type	Description
id	Number	The ID of the assignee
name optional	String	A unique name for the assignee
notes optional	String	Some notes to describe the assignee

Success 200

Field	Type	Description
id	Number	The internal id of the manufacturer
name	String	The name of the manufacturer
notes	String	Some notes to describe the assignee

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Michael's House of Installs",
    "notes": "If you give routers to Mike, put them here! Don't call him Mike."
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Update location

Update a physical inventory location

https://example.sonar.software/api/v1/inventory/inventory_locations/:id

Parameter

Field	Type	Description
id	Number	The ID of the location
name	String	The name of the location

Success 200

Field	Type	Description
id	Number	The internal id of the location
name	String	The name of the location

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "Not the Warehouse"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Update vehicle

Update a vehicle

https://example.sonar.software/api/v1/inventory/vehicles/:id

Parameter

Field	Type	Description
id	Number	The ID of the vehicle
name optional	String	The unique name of the vehicle
manufacturer optional	String	The vehicle manufacturer
model optional	String	The vehicle model
year optional	Number	The year the vehicle was constructed
license_plate optional	String	The license plate/number plate of the vehicle
vin optional	String	The VIN (vehicle identification number) of the vehicle

Success 200

Field	Type	Description
id	Number	The internal id of the vehicle
name	String	The name of the vehicle
manufacturer	String	The vehicle manufacturer
model	String	The vehicle model
year	Number	The year the vehicle was constructed
license_plate	String	The license plate/number plate of the vehicle
vin	String	The VIN (vehicle identification number) of the vehicle

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Bill's Work Van",
    "manufacturer": "Dadge",
    "model": "Rum",
    "year": "2014",
    "license_plate": "ABC123",
    "vin": "1231231234"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory Depletion Thresholds

Inventory_Depletion_Thresholds - Create a new depletion threshold

Create a new depletion threshold.

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds

Parameter

Field	Type	Description
enabled	Boolean	Whether or not the threshold is enabled. Disabled thresholds will not send alerts
threshold	Number	The quantity of items below which the threshold is triggered
type	String	The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below. Allowed values: `"aggregate"`, `"single"`
include_inventory_locations	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations
include_vehicles	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles
include_generic_inventory_assignees	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees
notified_user_ids	Array	An array of user IDs that are notified when this threshold is violated
included_inventory_location_ids	Array	If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to
included_vehicle_ids	Array	If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to
included_generic_inventory_assignee_ids	Array	If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

Success 200

Field	Type	Description
id	Number	The internal ID of the threshold
enabled	Boolean	Whether or not the threshold is enabled. Disabled thresholds will not send alerts
threshold	Number	The quantity of items below which the threshold is triggered
type	String	The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below. Allowed values: `"aggregate"`, `"single"`
include_inventory_locations	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations
include_vehicles	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles
include_generic_inventory_assignees	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees
notified_user_ids	Array	An array of user IDs that are notified when this threshold is violated
included_inventory_location_ids	Array	If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to
included_vehicle_ids	Array	If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to
included_generic_inventory_assignee_ids	Array	If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "enabled": true,
    "threshold": 100,
    "type": "aggregate",
    "include_inventory_locations": true,
    "include_vehicles": false,
    "include_generic_inventory_assignees": false,
    "notified_user_ids": [],
    "included_inventory_location_ids": [],
    "included_vehicle_ids": [],
    "included_generic_inventory_assignee_ids": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "notified_user_ids": "At least one user ID is not a valid user ID.",
         },
         "status_code": 422
     }
 }

Inventory_Depletion_Thresholds - Delete depletion threshold

Delete a manufacturer

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds/:depletion_threshold_id

Parameter

Field	Type	Description
id	Number	The ID of the depletion threshold

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the depletion threshold could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID could be found.",
         "status_code": 404
     }
 }

Inventory_Depletion_Thresholds - Get all depletion thresholds

Get a list of depletion thresholds for this model ID. A depletion threshold allows you to define criteria by which a group of users are notified when the quantity of items for a specific model falls below a certain threshold. This can also be constrained by specific assignees - for example, you can be notified when there are less than 50 widgets in your 'Main Warehouse' and less than 100 widgets across all inventory locations.

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
model_id	Number	The internal ID of the inventory model

Success 200

Field	Type	Description
id	Number	The internal ID of the threshold
enabled	Boolean	Whether or not the threshold is enabled. Disabled thresholds will not send alerts
threshold	Number	The quantity of items below which the threshold is triggered
type	String	The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below. Allowed values: `"aggregate"`, `"single"`
include_inventory_locations	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations
include_vehicles	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles
include_generic_inventory_assignees	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees
notified_user_ids	Array	An array of user IDs that are notified when this threshold is violated
included_inventory_location_ids	Array	If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to
included_vehicle_ids	Array	If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to
included_generic_inventory_assignee_ids	Array	If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "enabled": true,
      "threshold": 100,
      "type": "aggregate",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [],
      "included_inventory_location_ids": [],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    },
    {
      "id": 2,
      "enabled": true,
      "threshold": 100,
      "type": "aggregate",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [],
      "included_inventory_location_ids": [],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    },
    {
      "id": 3,
      "enabled": true,
      "threshold": 100,
      "type": "aggregate",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [
        1
      ],
      "included_inventory_location_ids": [],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    },
    {
      "id": 4,
      "enabled": true,
      "threshold": 100,
      "type": "aggregate",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [
        1
      ],
      "included_inventory_location_ids": [
        1
      ],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    },
    {
      "id": 5,
      "enabled": true,
      "threshold": 100,
      "type": "single",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [
        1
      ],
      "included_inventory_location_ids": [
        1
      ],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    }
  ],
  "paginator": {
    "total_count": 5,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Depletion_Thresholds - Get individual depletion threshold

Get an individual depletion threshold from a single model.

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds/:depletion_threshold_id

Parameter

Field	Type	Description
model_id	Number	The ID of an inventory model
depletion_threshold_id	Number	The ID of a depletion threshold

Success 200

Field	Type	Description
id	Number	The internal ID of the threshold
enabled	Boolean	Whether or not the threshold is enabled. Disabled thresholds will not send alerts
threshold	Number	The quantity of items below which the threshold is triggered
type	String	The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below. Allowed values: `"aggregate"`, `"single"`
include_inventory_locations	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations
include_vehicles	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles
include_generic_inventory_assignees	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees
notified_user_ids	Array	An array of user IDs that are notified when this threshold is violated
included_inventory_location_ids	Array	If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to
included_vehicle_ids	Array	If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to
included_generic_inventory_assignee_ids	Array	If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 1,
    "enabled": true,
    "threshold": 100,
    "type": "aggregate",
    "include_inventory_locations": true,
    "include_vehicles": false,
    "include_generic_inventory_assignees": false,
    "notified_user_ids": [],
    "included_inventory_location_ids": [],
    "included_vehicle_ids": [],
    "included_generic_inventory_assignee_ids": []
  }
}

Inventory_Depletion_Thresholds - Update depletion threshold

Update a depletion threshold.

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds/:depletion_threshold_id

Parameter

Field	Type	Description
model_id	Number	The ID of the inventory model
depletion_threshold_id	Number	The ID of the depletion threshold
enabled	Boolean	Whether or not the threshold is enabled. Disabled thresholds will not send alerts
threshold	Number	The quantity of items below which the threshold is triggered
type	String	The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below. Allowed values: `"aggregate"`, `"single"`
include_inventory_locations	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations
include_vehicles	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles
include_generic_inventory_assignees	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees
notified_user_ids	Array	An array of user IDs that are notified when this threshold is violated
included_inventory_location_ids	Array	If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to
included_vehicle_ids	Array	If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to
included_generic_inventory_assignee_ids	Array	If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

Success 200

Field	Type	Description
id	Number	The internal ID of the threshold
enabled	Boolean	Whether or not the threshold is enabled. Disabled thresholds will not send alerts
threshold	Number	The quantity of items below which the threshold is triggered
type	String	The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below. Allowed values: `"aggregate"`, `"single"`
include_inventory_locations	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations
include_vehicles	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles
include_generic_inventory_assignees	Boolean	If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees
notified_user_ids	Array	An array of user IDs that are notified when this threshold is violated
included_inventory_location_ids	Array	If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to
included_vehicle_ids	Array	If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to
included_generic_inventory_assignee_ids	Array	If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "enabled": true,
    "threshold": 50,
    "type": "single",
    "include_inventory_locations": true,
    "include_vehicles": false,
    "include_generic_inventory_assignees": false,
    "notified_user_ids": [
      1
    ],
    "included_inventory_location_ids": [
      1
    ],
    "included_vehicle_ids": [],
    "included_generic_inventory_assignee_ids": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "notified_user_ids": "One of the IDs in notified_user_ids is invalid."
         },
         "status_code": 422
     }
 }

Inventory Items

Inventory_Items - Create a new inventory model deployment type

Create a new inventory model deployment type.

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types

Parameter

Field	Type	Description
inventory_model_id	Integer	The ID of the inventory model to create the type for
deployment_type	String	A descriptive name for the inventory model deployment type

Success 200

Field	Type	Description
id	Integer	The ID of the inventory model deployment type.
deployment_type	String	The name of the inventory model deployment type

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Some test name",
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Inventory_Items - Create a new manufacturer

Create a new manufacturer.

https://example.sonar.software/api/v1/inventory/manufacturers

Parameter

Field	Type	Description
name	String	A unique name for the manufacturer

Success 200

Field	Type	Description
id	Number	The internal id of the manufacturer
name	String	The name of the manufacturer

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "name": "Cambium"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create a new model field

Create a new model field.

https://example.sonar.software/api/v1/inventory/models/:id/fields

Parameter

Field	Type	Description
id	Number	The ID of the model
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`, `"op_opc"`, `"lte_auth_key"`
is_required optional	Boolean	Whether or not the field is required to be completed when entering a new inventory item. If you do not add any fields, the item will be treated as generic, and can be added and reassigned by quantity. If an item has fields, is is unique and must always be referenced directly when adding and reassigning Default value: `true`
unique optional	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict. Default value: `false`
regexp optional	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. For example, you could validate a MAC address with "/^([a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$/". You can use https://regex101.com/ as a third party site to test/validate your regular expressions.

Success 200

Field	Type	Description
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`, `"op_opc"`, `"lte_auth_key"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, it will be null.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name is required.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create a new model field

Create a new model field.

https://example.sonar.software/api/v1/inventory/models/:id/fields

Parameter

Field	Type	Description
id	Number	The ID of the model
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`
is_required optional	Boolean	Whether or not the field is required to be completed when entering a new inventory item. If you do not add any fields, the item will be treated as generic, and can be added and reassigned by quantity. If an item has fields, is is unique and must always be referenced directly when adding and reassigning Default value: `true`
unique optional	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict. Default value: `false`
regexp optional	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. For example, you could validate a MAC address with "/^([a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$/". You can use https://regex101.com/ as a third party site to test/validate your regular expressions.

Success 200

Field	Type	Description
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, it will be null.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name is required.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create a new model

Create a new model.

https://example.sonar.software/api/v1/inventory/models

Parameter

Field	Type	Description
manufacturer_id	Number	The internal id of the manufacturer
name	String	The name of the model
inventory_model_category_id	Number	The category ID that this model is part of
https	Boolean	Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP
port	Integer	The TCP port to use for clickable links to IPs associated with this model

Success 200

Field	Type	Description
id	Number	The internal id of the model
name	String	The name of the model
manufacturer_id	Number	The ID of the manufacturer of the model
inventory_model_category_id	Number	The ID of the category that this model is part of
https	Boolean	Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP
port	Integer	The TCP port to use for clickable links to IPs associated with this model

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1,
       "https": true,
       "port": 443
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create a new model

Create a new model.

https://example.sonar.software/api/v1/inventory/models

Parameter

Field	Type	Description
manufacturer_id	Number	The internal id of the manufacturer
name	String	The name of the model
inventory_model_category_id	Number	The category ID that this model is part of

Success 200

Field	Type	Description
id	Number	The internal id of the model
name	String	The name of the model
manufacturer_id	Number	The ID of the manufacturer of the model
inventory_model_category_id	Number	The ID of the category that this model is part of

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create category

Create an inventory model category. This describes a group of inventory models and should be descriptive enough to be utilized in provisioning, monitoring, etc. For example, 'CPE Routers', 'CPE Radios' or 'GPON ONTs' is typically sufficiently descriptive but 'CPE' would not be.

https://example.sonar.software/api/v1/inventory/categories

Parameter

Field	Type	Description
name	String	The name of the category

Success 200

Field	Type	Description
id	Number	The ID of the category
name	String	The name of the category

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "CPE Radios"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name must be unique.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create inventory items

Create inventory items. This endpoint is slightly different than other endpoints as you must submit data in an array. This allows you to save multiple items at a time. It is recommended that you do validation on the input fields before submitting them here, as if you are submitting a large amount of items, a single invalid field will abort the entire insertion. If you are inserting very large quantities of items (1000) then make sure you set an adequate timeout on your connection, as it may take some additional time to process the data. You can also batch the insertions into groups in order to speed up processing.

https://example.sonar.software/api/v1/inventory/items

Parameter

Field	Type	Description
model_id	Number	The ID of an inventory model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
condition optional	String	The condition of the items Default value: `new` Allowed values: `"new"`, `"used"`
individualList optional	Array	An array of field objects, if items being added have fields. The format of the field object is a 'fields' property, which is an object with multiple properties representing field IDs, and values representing field data. See example below. If there are no fields defined and you are entering multiple generic items, use the 'quantity' option show below.
quantity optional	Number	Only valid if the item being added has no fields defined. You must either define quantity or individualList.
purchase_price optional	Number	Set the purchase price for the items, in your local currency. This is used for reporting purposes.

{
    "assignee_type": "generic_inventory_assignees",
    "assignee_id": 23,
    "model_id": 1305,
    "condition": "new",
    "individualList": [
        {
            "fields": {
                "1228": "This is the data for field ID 1228",
                "1229": "This is the data for field ID 1229"
            }
        },
        {
            "fields": {
                "1228": "This is the data for a second item being inserted for field ID 1228",
                "1229": "This is the data for a second item being inserted for field ID 1229"
            }
        }
    ]
}

{
    "assignee_type": "generic_inventory_assignees",
    "assignee_id": 23,
    "model_id": 1305,
    "quantity": 15
}

Success 200

Field	Type	Description
ids	Array	An array of inventory item IDs that have been created by this import

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "ids": [
       1,
       2,
       3,
       4
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The MAC Address field must be formatted as a MAC address in xx:xx:xx:xx:xx:xx format.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create inventory items

https://example.sonar.software/api/v1/inventory/items

Parameter

Field	Type	Description
model_id	Number	The ID of an inventory model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
condition optional	String	The condition of the items Default value: `new` Allowed values: `"new"`, `"used"`
individualList optional	Array	An array of field objects, if items being added have fields. The format of the field object is a 'fields' property, which is an object with multiple properties representing field IDs, and values representing field data. See example below. If there are no fields defined and you are entering multiple generic items, use the 'quantity' option show below.
quantity optional	Number	Only valid if the item being added has no fields defined. You must either define quantity or individualList.
purchase_price optional	Number	Set the purchase price for the items, in your local currency. This is used for reporting purposes.

{
    "assignee_type": "generic_inventory_assignees",
    "assignee_id": 23,
    "model_id": 1305,
    "condition": "new",
    "individualList": [
        {
            "fields": {
                "1228": "This is the data for field ID 1228",
                "1229": "This is the data for field ID 1229"
            }
        },
        {
            "fields": {
                "1228": "This is the data for a second item being inserted for field ID 1228",
                "1229": "This is the data for a second item being inserted for field ID 1229"
            }
        }
    ]
}

{
    "assignee_type": "generic_inventory_assignees",
    "assignee_id": 23,
    "model_id": 1305,
    "quantity": 15
}

Success 200

Field	Type	Description
ids	Array	An array of inventory item IDs that have been created by this import

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "ids": [
       1,
       2,
       3,
       4
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The MAC Address field must be formatted as a MAC address in xx:xx:xx:xx:xx:xx format.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Delete a inventory model deployment type

Delete a inventory model deployment type

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types/:id

Parameter

Field	Type	Description
inventory_model_id	Integer	The ID of the inventory model to delete the type from
id	Integer	The ID of the inventory model deployment type

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the inventory model deployment type could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "inventory model deployment type does not exist.",
         "status_code": 404
     }
 }

Inventory_Items - Delete category

Delete an inventory model category

https://example.sonar.software/api/v1/inventory/categories/:id

Parameter

Field	Type	Description
id	Number	The ID of the category

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the category could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Category cannot be deleted as inventory models are utilizing it.",
         "status_code": 422
     }
 }

Inventory_Items - Delete item

Delete an item. Generally, you don't want to do this unless you've made a mistake. If a unit is failed or sold, you should use the appropriate properties to denote that. Deleting items from inventory will destroy history.

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field	Type	Description
id	Number	The ID of the item

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the item could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Item cannot be deleted as it has been sold.",
         "status_code": 422
     }
 }

Inventory_Items - Delete manufacturer

Delete a manufacturer

https://example.sonar.software/api/v1/inventory/manufacturers/:id

Parameter

Field	Type	Description
id	Number	The ID of the manufacturer

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the manufacturer could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Manufacturer cannot be deleted as inventory models are utilizing it."
         "status_code": 422
     }
 }

Inventory_Items - Delete model field

Delete a model field. Deleting a field will also remove any data present in these fields on existing items.

https://example.sonar.software/api/v1/inventory/models/:model_id/fields/:field_id

Parameter

Field	Type	Description
model_id	Number	The ID of the model
field_id	Number	The ID of the field

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the model field could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Model field cannot be deleted as IP addresses are associated with this field on existing items.",
         "status_code": 422
     }
 }

Inventory_Items - Delete model

Delete a model

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field	Type	Description
id	Number	The ID of the model

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the model could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Model cannot be deleted as inventory items are utilizing it.",
         "status_code": 422
     }
 }

Inventory_Items - Get all categories

Get a list of categories.

https://example.sonar.software/api/v1/inventory/categories

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the category
name	String	The name of the category

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "CPE Radios"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all inventory items

Get all inventory items

https://example.sonar.software/api/v1/inventory/items/

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression
inventory_model_deployment_type_id optional	Number	The ID of a valid inventory model deployment type for this item.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "inventory_model_id": 2,
      "assignee_id": 1,
      "assignee_type": "users",
      "status": "functional",
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "Some data"
        },
        {
          "field_id": 2,
          "data": "00:AA:BB:CC:11:DD"
        }
      ],
      "inventory_model_deployment_type_id": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all inventory items

Get all inventory items

https://example.sonar.software/api/v1/inventory/items/

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
snmp_override	Array	An array containing a list of overridden fields to use for SNMP queries. See the 'Update SNMP Override' endpoint for details
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "inventory_model_id": 2,
      "assignee_id": 1,
      "assignee_type": "accounts",
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "AA:BB:CC:DD:EE:FF"
        }
      ],
      "snmp_override": []
    },
    {
      "id": 2,
      "inventory_model_id": 2,
      "assignee_id": 1,
      "assignee_type": "accounts",
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "12:12:12:12:12:AB"
        }
      ],
      "snmp_override": []
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all inventory items

Get all inventory items

https://example.sonar.software/api/v1/inventory/items/

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "inventory_model_id": 2,
      "assignee_id": 1,
      "assignee_type": "users",
      "status": "functional",
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "Some data"
        },
        {
          "field_id": 2,
          "data": "00:AA:BB:CC:11:DD"
        }
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all inventory model deployment types

Get all inventory model deployment types

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types

Parameter

Field	Type	Description
inventory_model_id	Integer	The ID of the inventory model to get the types for
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the inventory model deployment type.
deployment_type	String	The name of the deployment type

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "deployment_type": "Backhaul"
    },
    {
      "id": 1,
      "deployment_type": "Access Point"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all manufacturers

Get a list of manufacturers.

https://example.sonar.software/api/v1/inventory/manufacturers

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the manufacturer
name	String	The name of the manufacturer

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
            "id": 35,
            "name": "Cambium"
       },
       {
           "id": 36,
           "name": "Cisco"
       }
    ],
    "paginator": {
        "total_count": 3,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get all model fields

Get a list of model fields. This is not the data in the fields themselves - this is the definition of the fields on the model. When adding an inventory item, these fields will be present for each item.

https://example.sonar.software/api/v1/inventory/models/:id/fields

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the model

Success 200

Field	Type	Description
name	String	The name of the field
id	Number	The ID of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`, `"op_opc"`, `"lte_auth_key"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, it will be null.

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 9,
           "name": "MAC Address",
           "type": "mac",
           "is_required": true,
           "unique": true,
           "regexp": null
       }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get all model fields

https://example.sonar.software/api/v1/inventory/models/:id/fields

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the model

Success 200

Field	Type	Description
name	String	The name of the field
id	Number	The ID of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 9,
           "name": "MAC Address",
           "type": "mac",
           "is_required": true,
           "unique": true
       }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get all models

Get a list of models. A model is the descriptor for an item - e.g. a Cisco 2940 switch would have a model of '2940' and a manufacturer of 'Cisco'

https://example.sonar.software/api/v1/inventory/models

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the model
name	String	The name of the model
manufacturer_id	Number	The ID of the manufacturer of the model
inventory_model_category_id	Number	The ID of the category that this model is part of
https	Boolean	Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP
port	Integer	The TCP port to use for clickable links to IPs associated with this model

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 1,
           "name": "PMP450 5GHz AP",
           "manufacturer_id": 2,
           "inventory_model_category_id": 1,
           "https": false,
           "port": 80
       }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get all models

Get a list of models. A model is the descriptor for an item - e.g. a Cisco 2940 switch would have a model of '2940' and a manufacturer of 'Cisco'

https://example.sonar.software/api/v1/inventory/models

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the model
name	String	The name of the model
manufacturer_id	Number	The ID of the manufacturer of the model
inventory_model_category_id	Number	The ID of the category that this model is part of

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 1,
           "name": "PMP450 5GHz AP",
           "manufacturer_id": 2,
           "inventory_model_category_id": 1
       }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get an individual inventory model deployment type

Get an individual inventory model deployment type

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types/:id

Parameter

Field	Type	Description
inventory_model_id	Integer	The ID of the inventory model to get the type for
id	Integer	The ID of the inventory model deployment type

Success 200

Field	Type	Description
id	Integer	The ID of the inventory model deployment type.
deployment_type	String	The name of the deployment type

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "CPE"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Inventory_Items - Get individual category

Get an individual inventory model category.

https://example.sonar.software/api/v1/inventory/categories/:id

Parameter

Field	Type	Description
id	Number	The ID of the category

Success 200

Field	Type	Description
id	Number	The internal id of the category
name	String	The name of the category

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "CPE Radios"
  }
}

Inventory_Items - Get individual inventory item

Get an individual item.

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field	Type	Description
id	Number	The ID of the item

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression
inventory_model_deployment_type_id optional	Number	The ID of a valid inventory model deployment type for this item.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 2,
    "assignee_id": 1,
    "assignee_type": "users",
    "status": "functional",
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "Some data"
      },
      {
        "field_id": 2,
        "data": "00:AA:BB:CC:11:DD"
      }
    ],
    "inventory_model_deployment_type_id": null
  }
}

Inventory_Items - Get individual inventory item

Get an individual item.

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field	Type	Description
id	Number	The ID of the item

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
snmp_override	Array	An array containing a list of overridden fields to use for SNMP queries. See the 'Update SNMP Override' endpoint for details
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 2,
    "assignee_id": 1,
    "assignee_type": "accounts",
    "status": "functional",
    "purchase_price": 0,
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "AA:BB:CC:DD:EE:FF"
      }
    ],
    "snmp_override": []
  }
}

Inventory_Items - Get individual inventory item

Get an individual item.

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field	Type	Description
id	Number	The ID of the item

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 2,
    "assignee_id": 1,
    "assignee_type": "users",
    "status": "functional",
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "Some data"
      },
      {
        "field_id": 2,
        "data": "00:AA:BB:CC:11:DD"
      }
    ]
  }
}

Inventory_Items - Get individual manufacturer

Get an individual manufacturer.

https://example.sonar.software/api/v1/inventory/manufacturers/:id

Parameter

Field	Type	Description
id	Number	The ID of the manufacturer

Success 200

Field	Type	Description
id	Number	The internal id of the manufacturer
name	String	The name of the manufacturer

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "Cambium"
   }
}

Inventory_Items - Get individual model field

Get an individual model field.

https://example.sonar.software/api/v1/inventory/models/:model_id/fields/:field_id

Parameter

Field	Type	Description
model_id	Number	The ID of the model
field_id	Number	The ID of the field

Success 200

Field	Type	Description
id	Number	The ID of the field
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`, `"op_opc"`, `"lte_auth_key"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp	String	If this is a regular expression field, this will be the PCRE regexp to run against the contents. If empty, this will be null.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Inventory_Items - Get individual model field

Get an individual model field.

https://example.sonar.software/api/v1/inventory/models/:model_id/fields/:field_id

Parameter

Field	Type	Description
model_id	Number	The ID of the model
field_id	Number	The ID of the field

Success 200

Field	Type	Description
id	Number	The ID of the field
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp	String	If this is a regular expression field, this will be the PCRE regexp to run against the contents. If empty, this will be null.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Inventory_Items - Get individual model

Get an individual model.

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field	Type	Description
id	Number	The ID of the model

Success 200

Field	Type	Description
id	Number	The internal id of the model
name	String	The name of the model
manufacturer_id	Number	The ID of the manufacturer of the model
inventory_model_category_id	Number	The ID of the category that this model is part of
https	Boolean	Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP
port	Integer	The TCP port to use for clickable links to IPs associated with this model

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1,
       "https": false,
       "port": 12345
   }
}

Inventory_Items - Get individual model

Get an individual model.

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field	Type	Description
id	Number	The ID of the model

Success 200

Field	Type	Description
id	Number	The internal id of the model
name	String	The name of the model
manufacturer_id	Number	The ID of the manufacturer of the model
inventory_model_category_id	Number	The ID of the category that this model is part of

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1
   }
}

Inventory_Items - Mass delete items

Mass delete inventory items. Be very careful using this endpoint, you cannot restore deleted items!

https://example.sonar.software/api/v1/inventory/items

Parameter

Field	Type	Description
inventory_item_ids	Array	An array of inventory item IDs to be deleted.

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the items could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "Item cannot be deleted as the list of IDs is not valid.",
         "status_code": 422
     }
 }

Inventory_Items - Mass update inventory items

Mass update inventory items. This is frequently used in order to assign a large quantity of items to a new assignee, or to update the status of a group of items. You cannot update item fields using this endpoint - only the items themselves.

https://example.sonar.software/api/v1/inventory/items

Parameter

Field	Type	Description
assignee_type optional	String	The type of assignee to assign these items to. You can only move items to other entities that treat the items as undeployed. If you want to assign to an account, use the single update endpoint. Allowed values: `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id optional	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
item_ids	Array	An array that contains the IDs of all the items that should be updated.
status optional	String	The status of the items. Allowed values: `"functional"`, `"failed"`, `"lost"`
condition optional	String	The condition of the items. Allowed values: `"new"`, `"used"`
consumed optional	Boolean	Whether or not the item has been consumed.
purchase_price optional	Number	The purchase price of the items.

Example:

{
    "assignee_type": "users",
    "assignee_id": 1,
    "status": "failed",
    "item_ids": [
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        10,
        53,
        4938
    ]
}

Success 200

Field	Type	Description
success	Boolean	Will be true if the assignment was successful

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
       "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The item IDs 1,2,3,4 are not valid.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Mass update inventory items

https://example.sonar.software/api/v1/inventory/items

Parameter

Field	Type	Description
assignee_type optional	String	The type of assignee to assign these items to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id optional	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
item_ids	Array	An array that contains the IDs of all the items that should be updated.
status optional	String	The status of the items. Allowed values: `"functional"`, `"failed"`, `"lost"`
condition optional	String	The condition of the items. Allowed values: `"new"`, `"used"`
consumed optional	Boolean	Whether or not the item has been consumed.
purchase_price optional	Number	The purchase price of the items.

Example:

{
    "assignee_type": "users",
    "assignee_id": 1,
    "status": "failed",
    "item_ids": [
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        10,
        53,
        4938
    ]
}

Success 200

Field	Type	Description
success	Boolean	Will be true if the assignment was successful

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
       "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The item IDs 1,2,3,4 are not valid.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Update SNMP override

Override the SNMP authentication information for an item. This will override any defaults set on a monitoring template.

https://example.sonar.software/api/v1/inventory/items/:id/snmp_override

Parameter

Field	Type	Description
id	Number	The ID of the item
enabled	Boolean	Whether or not to enable the override Default value: `false`
snmp_version optional	Number	The SNMP version to use Allowed values: `1`, `2`, `3`
snmp_community optional	String	The SNMP community/security name to use
snmp3_sec_level optional	String	If you are using SNMPv3, this is the security level Allowed values: `"noAuthNoPriv"`, `"authNoPriv"`, `"authPriv"`
snmp3_auth_protocol optional	String	If you are using SNMPv3, this is the authentication protocol Allowed values: `"MD5"`, `"SHA"`
snmp3_auth_passphrase optional	String	If you are using SNMPv3, this is the authentication pass phrase
snmp3_priv_protocol optional	String	If you are using SNMPv3, this is the privacy protocol Allowed values: `"DES"`, `"AES"`
snmp3_priv_passphrase optional	String	If you are using SNMPv3, This is the privacy passphrase
snmp3_context_name optional	String	If you are using SNMPv3, this is the context name
snmp3_context_engine_id optional	String	If you are using SNMPv3, this is the default context EngineID

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
snmp_override	Array	An array containing a list of overridden fields to use for SNMP queries.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 2,
    "assignee_id": 1,
    "assignee_type": "accounts",
    "status": "functional",
    "purchase_price": 0,
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "AA:BB:CC:DD:EE:FF"
      }
    ],
    "snmp_override": {
      "enabled": true,
      "snmp_version": 2,
      "snmp_community": "public",
      "snmp3_sec_level": null,
      "snmp3_auth_protocol": null,
      "snmp3_auth_passphrase": null,
      "snmp3_priv_protocol": null,
      "snmp3_priv_passphrase": null,
      "snmp3_context_name": null,
      "snmp3_context_engine_id": null
    }
  }
}

Inventory_Items - Update category

Update an individual inventory model category

https://example.sonar.software/api/v1/inventory/categories/:id

Parameter

Field	Type	Description
id	Number	The ID of the inventory model category
name	String	The name for the inventory model category

Success 200

Field	Type	Description
id	Number	The ID of the category
name	String	The name of the category

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "CPE Radios"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name must be unique.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Update inventory item

Update an individual inventory item

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field	Type	Description
id	Number	The ID of the inventory item
assignee_type optional	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id optional	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status optional	String	The status of the device Allowed values: `"functional"`, `"failed"`, `"lost"`
condition optional	String	The condition of the device Allowed values: `"new"`, `"used"`
purchase_price optional	Number	The purchase price of the item, in local currency. This is used for reporting.
consumed optional	Boolean	If this is a consumable item (e.g. a spool of Ethernet cable) and the spool is consumed, set this to true.
fields optional	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression
inventory_model_deployment_type_id optional	Number	The ID of a valid inventory model deployment type for this item.

Example:

{
    "assignee_type": "vehicles",
    "assignee_id": 3,
    "status": "functional",
    "purchase_price": 10.53,
    "condition": "new",
    "fields": [
        {
            "field_id": 6,
            "data": "00:AA:BB:CC:DD:EF"
        },
        {
            "field_id": 7,
            "data": "Some data I want to store"
        }
    ],
    "inventory_model_deployment_type_id": 2
}

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
       "id": 68
       "inventory_model_id": 1,
       "assignee_type": "vehicles",
       "assignee_id": 3,
       "status": "functional",
       "consumed": false,
       "consumed_at": null
       "fields": [
           {
               "field_id": 6,
               "data": "00:AA:BB:CC:DD:EF"
           },
           {
               "field_id": 7,
               "data": "Some data I want to store"
           }
       ],
       "inventory_model_deployment_type_id": 2
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The MAC Address field must be formatted as a MAC address in xx:xx:xx:xx:xx:xx format.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Update inventory item

Update an individual inventory item

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field	Type	Description
id	Number	The ID of the inventory item
assignee_type optional	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id optional	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status optional	String	The status of the device Allowed values: `"functional"`, `"failed"`, `"lost"`
condition optional	String	The condition of the device Allowed values: `"new"`, `"used"`
purchase_price optional	Number	The purchase price of the item, in local currency. This is used for reporting.
consumed optional	Boolean	If this is a consumable item (e.g. a spool of Ethernet cable) and the spool is consumed, set this to true.
fields optional	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Example:

{
    "assignee_type": "vehicles",
    "assignee_id": 3,
    "status": "functional",
    "purchase_price": 10.53,
    "condition": "new",
    "fields": [
        {
            "field_id": 6,
            "data": "00:AA:BB:CC:DD:EF"
        },
        {
            "field_id": 7,
            "data": "Some data I want to store"
        }
    ]
}

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
assignee_type	String	The type of assignee to assign this item to Allowed values: `"accounts"`, `"network_sites"`, `"inventory_locations"`, `"vehicles"`, `"generic_inventory_assignees"`, `"users"`
assignee_id	Number	The ID of the assignee (e.g. the ID of the vehicle, account, etc)
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
       "id": 68
       "inventory_model_id": 1,
       "assignee_type": "vehicles",
       "assignee_id": 3,
       "status": "functional",
       "consumed": false,
       "consumed_at": null
       "fields": [
           {
               "field_id": 6,
               "data": "00:AA:BB:CC:DD:EF"
           },
           {
               "field_id": 7,
               "data": "Some data I want to store"
           }
       ]
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The MAC Address field must be formatted as a MAC address in xx:xx:xx:xx:xx:xx format.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Update inventory model deployment type

Update an existing inventory model deployment type.

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types/:id

Parameter

Field	Type	Description
inventory_model_id	Integer	The ID of the inventory model to update the type for
id	Integer	The inventory model deployment type ID
deployment_type	String	The name of the deployment type

Success 200

Field	Type	Description
id	Integer	The ID of the inventory model deployment type.
deployment_type	String

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "deployment_type": "Backhaul"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Inventory_Items - Update manufacturer

Update a manufacturer

https://example.sonar.software/api/v1/inventory/manufacturers/:id

Parameter

Field	Type	Description
id	Number	The ID of the manufacturer
name	String	The name of the manufacturer

Success 200

Field	Type	Description
id	Number	The internal id of the manufacturer
name	String	The name of the manufacturer

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "Cambium"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory_Items - Update model field

Update a model field. When modifying existing fields, all existing data must adhere to the new type. For example, if you change a field from "string" to "mac", all existing data must match the requirements of the "mac" format.

https://example.sonar.software/api/v1/inventory/models/:id/fields/:field_id

Parameter

Field	Type	Description
id	Number	The ID of the model
field_id	Number	The ID of the field
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`, `"op_opc"`, `"lte_auth_key"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp optional	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. For example, you could validate a MAC address with "/^([a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$/". You can use https://regex101.com/ as a third party site to test/validate your regular expressions.

Success 200

Field	Type	Description
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`, `"op_opc"`, `"lte_auth_key"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, this will be null.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "You cannot enable the unique attribute on field MAC Address because there is duplicated data on existing items.",
     "status_code": 422
   }
 }

Inventory_Items - Update model field

https://example.sonar.software/api/v1/inventory/models/:id/fields/:field_id

Parameter

Field	Type	Description
id	Number	The ID of the model
field_id	Number	The ID of the field
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp optional	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. For example, you could validate a MAC address with "/^([a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$/". You can use https://regex101.com/ as a third party site to test/validate your regular expressions.

Success 200

Field	Type	Description
name	String	The name of the field
type	String	The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format. Allowed values: `"string"`, `"integer"`, `"decimal"`, `"mac"`, `"imsi"`, `"regexp"`
is_required	Boolean	Whether or not the field is required to be completed when entering a new inventory item
unique	Boolean	Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.
regexp	String	If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, this will be null.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "You cannot enable the unique attribute on field MAC Address because there is duplicated data on existing items.",
     "status_code": 422
   }
 }

Inventory_Items - Update model

Update a model

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field	Type	Description
id	Number	The ID of the model
manufacturer_id	Number	The internal id of the manufacturer
name	String	The name of the model
inventory_model_category_id	Number	The category that this model is part of
https	Boolean	Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP
port	Integer	The TCP port to use for clickable links to IPs associated with this model

Success 200

Field	Type	Description
id	Number	The internal id of the model
name	String	The name of the model
manufacturer_id	Number	The ID of the manufacturer of the model
inventory_model_category_id	Number	The ID of the category that this model is part of
https	Boolean	Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP
port	Integer	The TCP port to use for clickable links to IPs associated with this model

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1,
       "https": false,
       "port": 432
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory_Items - Update model

Update a model

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field	Type	Description
id	Number	The ID of the model
manufacturer_id optional	Number	The internal id of the manufacturer
name optional	String	The name of the model
inventory_model_category_id optional	Number	The category that this model is part of

Success 200

Field	Type	Description
id	Number	The internal id of the model
name	String	The name of the model
manufacturer_id	Number	The ID of the manufacturer of the model
inventory_model_category_id	Number	The ID of the category that this model is part of

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory Location Addresses

Inventory_Location_Addresses - Create inventory location address

Create a new inventory location address

https://example.sonar.software/api/v1/inventory_locations/:inventory_location_id/addresses

Parameter

Field	Type	Description
inventory_location_id	Number	The ID of the inventory location to add the address to
line1	String	The first line of the address
line2 optional	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
county	String	The county, for US addresses
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 3,
        "line1": "555 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Inventory_Location_Addresses - Delete inventory location address

Delete an inventory location address

https://example.sonar.software/api/v1/inventory_locations/:inventory_location_id/addresses/:address_id

Parameter

Field	Type	Description
inventory_location_id	Number	The ID of the inventory location
address_id	Number	The ID of the address

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "Address deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the address could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Inventory_Location_Addresses - Get all inventory location addresses

Get a list of the addresses for inventory location ID :inventory_location_id

https://example.sonar.software/api/v1/inventory_location/:inventory_location_id/addresses

Parameter

Field	Type	Description
inventory_location_id	Number	The ID of the inventory location
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
county	String	A valid county for the subdivision obtained from /_data/counties, null if not a US address

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "line1": "12345 Some Ln",
            "line2": "",
            "city": "West Allis",
            "state": "Wisconsin",
            "county": "Milwaukee Co.",
            "zip": "53226",
            "country": "US",
            "latitude": null,
            "longitude": null,
            "address_type_id": 1
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Location_Addresses - Get individual inventory location address

Get an individual inventory location address.

https://example.sonar.software/api/v1/inventory_locations/:inventory_location_id/addresses/:address_id

Parameter

Field	Type	Description
inventory_location_id	Number	The ID of the inventory location
address_id	Number	The ID of the address
county	String	A valid county for the subdivision obtained from /_data/counties, null if not a US address

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
       "line1": "12345 Some Ln",
       "line2": "",
       "city": "West Allis",
       "state": "Wisconsin",
       "county": "Milwaukee Co.",
       "zip": "53226",
       "country": "US",
       "latitude": null,
       "longitude": null,
       "address_type_id": 1
    }
}

Inventory_Location_Addresses - Update inventory location address

Update an inventory location address.

https://example.sonar.software/api/v1/inventory_locations/:inventory_location_id/addresses/:address_id

Parameter

Field	Type	Description
inventory_location_id	Number	The ID of the inventory location to update the address on
address_id	Number	The ID of the address
line1 optional	String	The first line of the address
line2 optional	String	The second line of the address, typically used for a suite number, apartment number, etc
city optional	String	The city
state optional	String	The state, province or other country subdivision
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.
zip optional	String	The ZIP/postal code
country optional	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude optional	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude optional	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id optional	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and will be null for any other country.
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "line1": "444 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Invoice Messages

Invoice_Messages - Create a new invoice message

Create a new invoice message.

https://example.sonar.software/api/v1/financial/invoices/invoice_messages

Parameter

Field	Type	Description
name	String	A name for the invoice message
message	String	The invoice message
account_type_ids	Array	An array of account type IDs that this invoice message should be appended for

Success 200

Field	Type	Description
id	Integer	The ID of the invoice message.
name	String	The name of the invoice message
message	String	The invoice message
account_type_ids	Array	An array of account type IDs that this invoice message should be appended for

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 7,
    "name": "Commercial Message",
    "message": "Please remit payment through our business portal at www.example.biz",
    "account_type_ids": [
      2
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "account_type_ids": "You must input at least one account type ID."
     },
     "status_code": 422
   }
 }

Invoice_Messages - Delete a invoice message

Delete a invoice message

https://example.sonar.software/api/v1/financial/invoices/invoice_messages/:id

Parameter

Field	Type	Description
id	Integer	The ID of the invoice message

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the invoice message could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "invoice message does not exist.",
         "status_code": 404
     }
 }

Invoice_Messages - Get all invoice messages

Get all invoice messages

https://example.sonar.software/api/v1/financial/invoices/invoice_messages

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the invoice message.
name	String	The name of the invoice message
message	String	The invoice message
account_type_ids	Array	An array of account type IDs that this invoice message should be appended for

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 6,
      "name": "Test message",
      "message": "This is a test message, I hope nobody sees it!",
      "account_type_ids": [
        1
      ]
    },
    {
      "id": 7,
      "name": "Commercial Message",
      "message": "Please remit payment through our business portal at www.example.biz",
      "account_type_ids": [
        2
      ]
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Invoice_Messages - Get an individual invoice message

Get an individual invoice message

https://example.sonar.software/api/v1/financial/invoices/invoice_messages/:id

Parameter

Field	Type	Description
id	Integer	The ID of the invoice message

Success 200

Field	Type	Description
id	Integer	The ID of the invoice message.
name	String	The name of the invoice message
message	String	The invoice message
account_type_ids	Array	An array of account type IDs that this invoice message should be appended for

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "name": "Commercial Message",
    "message": "Please remit payment through our business portal at www.example.biz",
    "account_type_ids": [
      2
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Invoice_Messages - Update invoice message

Update an existing invoice message.

https://example.sonar.software/api/v1/financial/invoices/invoice_messages/:id

Parameter

Field	Type	Description
id	Integer	The invoice message ID
name	String	A name for the invoice message
message	String	The invoice message
account_type_ids	Array	An array of account type IDs that this invoice message should be appended for

Success 200

Field	Type	Description
id	Integer	The ID of the invoice message.
name	String	The name of the invoice message
message	String	The invoice message
account_type_ids	Array	An array of account type IDs that this invoice message should be appended for

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "name": "Commercial Message",
    "message": "Please remit payment through our business portal at www.example.software",
    "account_type_ids": [
      2
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Job Types

Job_Types - Create a new job type

Create a new job type.

https://example.sonar.software/api/v1/scheduling/job_types

Parameter

Field	Type	Description
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion optional	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed Default value: `false`
account_status_id_completion optional	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure optional	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed Default value: `false`
account_status_id_failure optional	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket optional	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed Default value: `false`
completion_ticket_group_id optional	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket optional	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed Default value: `false`
failure_ticket_group_id optional	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks optional	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them Default value: `true`
task_template_id optional	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services optional	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.
contract_template_id optional	Integer	Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

Success 200

Field	Type	Description
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed
account_status_id_completion	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed
account_status_id_failure	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed
completion_ticket_group_id	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed
failure_ticket_group_id	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them
task_template_id	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.
contract_template_id optional	Integer	Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 6,
    "name": "Donut Run",
    "length_in_minutes": 15,
    "color": "orange",
    "icon": "cookie",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": true,
    "task_template_id": null,
    "services": [],
    "contract_template_id": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "account_status_id_completion": "The account status id completion field is required when change status on completion is 1."
     },
     "status_code": 422
   }
 }

Job_Types - Create a new job type

Create a new job type.

https://example.sonar.software/api/v1/scheduling/job_types

Parameter

Field	Type	Description
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion optional	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed Default value: `false`
account_status_id_completion optional	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure optional	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed Default value: `false`
account_status_id_failure optional	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket optional	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed Default value: `false`
completion_ticket_group_id optional	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket optional	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed Default value: `false`
failure_ticket_group_id optional	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks optional	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them Default value: `true`
task_template_id optional	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services optional	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

Success 200

Field	Type	Description
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed
account_status_id_completion	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed
account_status_id_failure	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed
completion_ticket_group_id	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed
failure_ticket_group_id	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them
task_template_id	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 6,
    "name": "Donut Run",
    "length_in_minutes": 15,
    "color": "orange",
    "icon": "cookie",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": true,
    "task_template_id": null,
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "account_status_id_completion": "The account status id completion field is required when change status on completion is 1."
     },
     "status_code": 422
   }
 }

Job_Types - Delete a job type

Delete a job type

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field	Type	Description
id	Integer	The ID of the job type

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the job type could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "job type does not exist.",
         "status_code": 404
     }
 }

Job_Types - Get all job types

Get all job types

https://example.sonar.software/api/v1/scheduling/job_types

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the job type.
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed
account_status_id_completion	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed
account_status_id_failure	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed
completion_ticket_group_id	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed
failure_ticket_group_id	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them
task_template_id	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.
contract_template_id optional	Integer	Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Installation",
      "length_in_minutes": 90,
      "color": "blue",
      "icon": "smile",
      "change_status_on_completion": false,
      "account_status_id_completion": null,
      "change_status_on_failure": false,
      "account_status_id_failure": null,
      "create_completion_ticket": false,
      "completion_ticket_group_id": null,
      "create_failure_ticket": false,
      "failure_ticket_group_id": null,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": [],
      "contract_template_id": 1
    },
    {
      "id": 2,
      "name": "Service Call",
      "length_in_minutes": 120,
      "color": "orange",
      "icon": "book",
      "change_status_on_completion": false,
      "account_status_id_completion": null,
      "change_status_on_failure": false,
      "account_status_id_failure": null,
      "create_completion_ticket": false,
      "completion_ticket_group_id": null,
      "create_failure_ticket": false,
      "failure_ticket_group_id": null,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": [],
      "contract_template_id": null
    },
    {
      "id": 3,
      "name": "Job with services",
      "length_in_minutes": 15,
      "color": "purple",
      "icon": "folder",
      "change_status_on_completion": true,
      "account_status_id_completion": 4,
      "change_status_on_failure": true,
      "account_status_id_failure": 3,
      "create_completion_ticket": true,
      "completion_ticket_group_id": 1,
      "create_failure_ticket": true,
      "failure_ticket_group_id": 1,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": [
        9,
        8
      ],
      "contract_template_id": null
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Job_Types - Get all job types

Get all job types

https://example.sonar.software/api/v1/scheduling/job_types

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the job type.
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed
account_status_id_completion	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed
account_status_id_failure	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed
completion_ticket_group_id	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed
failure_ticket_group_id	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them
task_template_id	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Installation",
      "length_in_minutes": 90,
      "color": "blue",
      "icon": "smile",
      "change_status_on_completion": false,
      "account_status_id_completion": null,
      "change_status_on_failure": false,
      "account_status_id_failure": null,
      "create_completion_ticket": false,
      "completion_ticket_group_id": null,
      "create_failure_ticket": false,
      "failure_ticket_group_id": null,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": []
    },
    {
      "id": 2,
      "name": "Service Call",
      "length_in_minutes": 120,
      "color": "orange",
      "icon": "book",
      "change_status_on_completion": false,
      "account_status_id_completion": null,
      "change_status_on_failure": false,
      "account_status_id_failure": null,
      "create_completion_ticket": false,
      "completion_ticket_group_id": null,
      "create_failure_ticket": false,
      "failure_ticket_group_id": null,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": []
    },
    {
      "id": 3,
      "name": "Job with services",
      "length_in_minutes": 15,
      "color": "purple",
      "icon": "folder",
      "change_status_on_completion": true,
      "account_status_id_completion": 4,
      "change_status_on_failure": true,
      "account_status_id_failure": 3,
      "create_completion_ticket": true,
      "completion_ticket_group_id": 1,
      "create_failure_ticket": true,
      "failure_ticket_group_id": 1,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": [
        9,
        8
      ]
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Job_Types - Get an individual job type

Get an individual job type

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field	Type	Description
id	Integer	The ID of the job type

Success 200

Field	Type	Description
id	Integer	The ID of the job type.
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed
account_status_id_completion	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed
account_status_id_failure	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed
completion_ticket_group_id	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed
failure_ticket_group_id	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them
task_template_id	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.
contract_template_id optional	Integer	Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Installation",
    "length_in_minutes": 90,
    "color": "blue",
    "icon": "smile",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": false,
    "task_template_id": null,
    "services": [],
    "contract_template_id": null
  }
}}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Job_Types - Get an individual job type

Get an individual job type

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field	Type	Description
id	Integer	The ID of the job type

Success 200

Field	Type	Description
id	Integer	The ID of the job type.
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed
account_status_id_completion	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed
account_status_id_failure	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed
completion_ticket_group_id	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed
failure_ticket_group_id	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them
task_template_id	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Installation",
    "length_in_minutes": 90,
    "color": "blue",
    "icon": "smile",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": false,
    "task_template_id": null,
    "services": []
  }
}}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Job_Types - Update job type

Update an existing job type.

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field	Type	Description
id	Integer	The ID of the job type
name optional	String	The name of the job type
length_in_minutes optional	Integer	The default length of time assigned for jobs of this type to be completed
color optional	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon optional	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion optional	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed Default value: `false`
account_status_id_completion optional	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure optional	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed Default value: `false`
account_status_id_failure optional	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket optional	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed Default value: `false`
completion_ticket_group_id optional	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket optional	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed Default value: `false`
failure_ticket_group_id optional	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks optional	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them Default value: `true`
task_template_id optional	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services optional	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.
contract_template_id optional	Integer	Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

Success 200

Field	Type	Description
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed
account_status_id_completion	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed
account_status_id_failure	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed
completion_ticket_group_id	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed
failure_ticket_group_id	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them
task_template_id	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.
contract_template_id optional	Integer	Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 6,
    "name": "Donut Walk",
    "length_in_minutes": 15,
    "color": "orange",
    "icon": "cookie",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": true,
    "task_template_id": null,
    "services": [],
    "contract_template_id": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Job_Types - Update job type

Update an existing job type.

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field	Type	Description
id	Integer	The ID of the job type
name optional	String	The name of the job type
length_in_minutes optional	Integer	The default length of time assigned for jobs of this type to be completed
color optional	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon optional	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion optional	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed Default value: `false`
account_status_id_completion optional	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure optional	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed Default value: `false`
account_status_id_failure optional	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket optional	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed Default value: `false`
completion_ticket_group_id optional	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket optional	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed Default value: `false`
failure_ticket_group_id optional	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks optional	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them Default value: `true`
task_template_id optional	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services optional	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

Success 200

Field	Type	Description
name	String	The name of the job type
length_in_minutes	Integer	The default length of time assigned for jobs of this type to be completed
color	String	The color of the job type on the schedule Allowed values: `"blue"`, `"green"`, `"red"`, `"purple"`, `"yellow"`, `"orange"`, `"grey"`
icon	String	The icon shown on jobs of this type on the schedule Allowed values: `"smile"`, `"frown"`, `"graph"`, `"jellyfish"`, `"car"`, `"folder"`, `"cookie"`, `"book"`, `"dna"`, `"box"`
change_status_on_completion	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are completed
account_status_id_completion	Integer	If `change_status_on_completion` is `true`, this is the account status ID that the account will be changed to when jobs of this type are completed
change_status_on_failure	Boolean	Set this to `true` if you want the status on an account to be changed when jobs of this type are failed
account_status_id_failure	Integer	If `change_status_on_failure` is `true`, this is the account status ID the account will be changed to when jobs of this type are failed
create_completion_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are completed
completion_ticket_group_id	Integer	If `create_completion_ticket` is `true`, then tickets created on completion will be assigned to this ticket group ID
create_failure_ticket	Boolean	If this is `true`, a ticket will be created when jobs of this type are failed
failure_ticket_group_id	Integer	If `create_failure_ticket` is `true`, then tickets created on failure will be assigned to this ticket group ID
allow_completion_with_uncompleted_tasks	Boolean	If this is `false`, jobs of this type cannot be completed while they have uncompleted tasks on them
task_template_id	Integer	Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type
services	Array	An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 6,
    "name": "Donut Walk",
    "length_in_minutes": 15,
    "color": "orange",
    "icon": "cookie",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": true,
    "task_template_id": null,
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs

Jobs - Check in to a job

Check a user in to a job. This is used when the user is on site and starting the job. Multiple users can check in to a job at the same time.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_in

Parameter

Field	Type	Description
id	Integer	The job ID
user_id	Integer	The ID of the user to check in to the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
completed_at	DateTime	The date and time the job was completed, if it is complete.
completed_by_user_id	Integer	The ID of the user that completed the job, if it is complete.
completed_successfully	Boolean	If the job is complete, this will be `true` or `false` to show if the job was completed successfully.
completion_reason	String	The reason given upon job completion, if the job is complete.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [
         [
              "user_id": 1,
              "datetime": "2016-01-01 01:01:01"
         ]
    ],
    "services": [
        1
    ] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check in to a job

Check a user in to a job. This is used when the user is on site and starting the job. Multiple users can check in to a job at the same time.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_in

Parameter

Field	Type	Description
id	Integer	The job ID
user_id	Integer	The ID of the user to check in to the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [
         [
              "user_id": 1,
              "datetime": "2016-01-01 01:01:01"
         ]
    ],
    "services": [
        1
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check in to a job

Check a user in to a job. This is used when the user is on site and starting the job. Multiple users can check in to a job at the same time.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_in

Parameter

Field	Type	Description
id	Integer	The job ID
user_id	Integer	The ID of the user to check in to the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [
         [
              "user_id": 1,
              "datetime": "2016-01-01 01:01:01"
         ]
    ],
    "services": [
        1
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check out of a job

Check a user out of a job. This should only be used to remove a user from a checked in job prior to completion. Completing or failing a job will automatically remove all checked in users.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_out

Parameter

Field	Type	Description
id	Integer	The job ID
user_id	Integer	The ID of the user to check out of the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
completed_at	DateTime	The date and time the job was completed, if it is complete.
completed_by_user_id	Integer	The ID of the user that completed the job, if it is complete.
completed_successfully	Boolean	If the job is complete, this will be `true` or `false` to show if the job was completed successfully.
completion_reason	String	The reason given upon job completion, if the job is complete.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": [] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check out of a job

Check a user out of a job. This should only be used to remove a user from a checked in job prior to completion. Completing or failing a job will automatically remove all checked in users.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_out

Parameter

Field	Type	Description
id	Integer	The job ID
user_id	Integer	The ID of the user to check out of the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check out of a job

Check a user out of a job. This should only be used to remove a user from a checked in job prior to completion. Completing or failing a job will automatically remove all checked in users.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_out

Parameter

Field	Type	Description
id	Integer	The job ID
user_id	Integer	The ID of the user to check out of the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Complete a job

Completing a job will move the status to completed or failed, remove it from the schedule, remove all checked in users, add any services to the account that are associated with the job, and perform all events associated with the job type.

https://example.sonar.software/api/v1/scheduling/jobs/:id/complete

Parameter

Field Type Description

Integer

The job ID

completion_type

String

,"failure" Whether or not the job was successfully completed

Default value: success

reason optional

String

The reason for the job failure, or some notes on success. Required when failing a job.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
completed_at	DateTime	The date and time the job was completed, if it is complete.
completed_by_user_id	Integer	The ID of the user that completed the job, if it is complete.
completed_successfully	Boolean	If the job is complete, this will be `true` or `false` to show if the job was completed successfully.
completion_reason	String	The reason given upon job completion, if the job is complete.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "completed",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": [] ,
    "completed_at": "2018-09-23 12:23:34,
    "completed_by_user_id": 1,
    "completed_successfully": true,
    "completion_reason": "foobar"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Complete a job

https://example.sonar.software/api/v1/scheduling/jobs/:id/complete

Parameter

Field Type Description

Integer

The job ID

completion_type

String

,"failure" Whether or not the job was successfully completed

Default value: success

reason optional

String

The reason for the job failure, or some notes on success. Required when failing a job.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "completed",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Complete a job

https://example.sonar.software/api/v1/scheduling/jobs/:id/complete

Parameter

Field Type Description

Integer

The job ID

completion_type

String

,"failure" Whether or not the job was successfully completed

Default value: success

reason optional

String

The reason for the job failure, or some notes on success. Required when failing a job.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "completed",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Create a new desired job date/time

Create a new desired job date/time. This lets you specify when a customer would like to have the job performed as a date, a start time, and an end time, which denotes the range of time they will be available.

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes

Parameter

Field	Type	Description
id	Number	The ID of the job
date	Date	The date, in Y-m-d format
start_time	Time	The start time of the time range, in H:m:s format (24 hour)
end_time	Time	The end time of the time range, in H:m:s format (24 hour)

Success 200

Field	Type	Description
id	Number	The ID of the desired job date/time.
date	Date	The date, in Y-m-d format
start_time	Time	The start time of the time range, in H:m:s format (24 hour)
end_time	Time	The end time of the time range, in H:m:s format (24 hour)

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "date": "2016-09-01",
    "start_time": "07:00:00",
    "end_time": "09:00:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "The start_time must be prior to the end_time.",
     "status_code": 422
   }
 }

Jobs - Create a new job

Create a new job.

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field	Type	Description
job_type_id	Number	The ID of a job type
assigned_type	String	The entity you are assigning this job to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity
length_in_minutes optional	Number	The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.
notes optional	String	Any notes for the job.
scheduled_datetime optional	DateTime	If you want to schedule or reschedule this job, input a date/time to schedule it for. `user_ids` is required if this is submitted. The timezone should be the timezone of this Sonar instance.
user_ids optional	Array	Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. `scheduled_datetime` is required if this is submitted.
services optional	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
ticket_id optional	Integer	ID of a ticket that this job is linked to. If `null` is sent, the job will not be linked to a ticket.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
completed_at	DateTime	The date and time the job was completed, if it is complete.
completed_by_user_id	Integer	The ID of the user that completed the job, if it is complete.
completed_successfully	Boolean	If the job is complete, this will be `true` or `false` to show if the job was completed successfully.
completion_reason	String	The reason given upon job completion, if the job is complete.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "There is no availability for that day/time for user ID 1.",
     "status_code": 422
   }
 }

Jobs - Create a new job

Create a new job.

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field	Type	Description
job_type_id	Number	The ID of a job type
assigned_type	String	The entity you are assigning this job to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity
length_in_minutes optional	Number	The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.
notes optional	String	Any notes for the job.
scheduled_datetime optional	DateTime	If you want to schedule or reschedule this job, input a date/time to schedule it for. `user_ids` is required if this is submitted. The timezone should be the timezone of this Sonar instance.
user_ids optional	Array	Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. `scheduled_datetime` is required if this is submitted.
services optional	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
ticket_id optional	Integer	ID of a ticket that this job is linked to. If `null` is sent, the job will not be linked to a ticket.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "There is no availability for that day/time for user ID 1.",
     "status_code": 422
   }
 }

Jobs - Create a new job

Create a new job.

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field	Type	Description
job_type_id	Number	The ID of a job type
assigned_type	String	The entity you are assigning this job to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity
length_in_minutes optional	Number	The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.
notes optional	String	Any notes for the job.
scheduled_datetime optional	DateTime	If you want to schedule or reschedule this job, input a date/time to schedule it for. `user_ids` is required if this is submitted. The timezone should be the timezone of this Sonar instance.
user_ids optional	Array	Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. `scheduled_datetime` is required if this is submitted.
services optional	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "There is no availability for that day/time for user ID 1.",
     "status_code": 422
   }
 }

Jobs - Delete a desired job date/time

Delete a desired job date/time

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes/:desired_job_datetime_id

Parameter

Field	Type	Description
id	Number	The ID of the job
desired_job_datetime_id	Number	The ID of the desired job date/time

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the desired job date/time could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "desired job date/time does not exist.",
         "status_code": 404
     }
 }

Jobs - Delete a job

Delete a job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field	Type	Description
id	Number	The ID of the job

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the job could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "job does not exist.",
         "status_code": 404
     }
 }

Jobs - Delete a job

Delete a job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field	Type	Description
id	Number	The ID of the job

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the job could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "job does not exist.",
         "status_code": 404
     }
 }

Jobs - Find any available space for a job

https://example.sonar.software/api/v1/scheduling/jobs/find_any_available_space

Parameter

Field	Type	Description
start_date	DateTime	The start date for the date range in YYYY-MM-DD format.
end_date	DateTime	The end date for the date range in YYYY-MM-DD format.
length_in_minutes	Integer	The length of time required for the job, in minutes
job_type_id	Integer	A valid job type ID
users optional	Array	An array of user IDs that you want to schedule this job for. If this is omitted, all users will be checked.
entityType	String	One of `account` or `network_site`. This is to limit results to entries that meet any defined geofences.
entityId	Integer	The ID of an `account` or `network_site`. This is to limit results to entries that meet any defined geofences.

Success 200

Field	Type	Description
data	Object	An object of results, where the primary property is the date. Below that are multiple objects, where the property is the user ID, and the value is an array of objects with `start` and `end`, showing the available time blocks that match the criteria.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "2016-09-16": {
      "1": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "15:47:00"
        },
        {
          "start": "16:02:00",
          "end": "17:20:00"
        },
        {
          "start": "18:20:00",
          "end": "21:00:00"
        }
      ],
      "2": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "16:56:00"
        },
        {
          "start": "17:26:00",
          "end": "21:00:00"
        }
      ]
    }
  }
}

Jobs - Find any available space for a job

https://example.sonar.software/api/v1/scheduling/jobs/find_any_available_space

Parameter

Field	Type	Description
start_date	DateTime	The start date for the date range in YYYY-MM-DD format.
end_date	DateTime	The end date for the date range in YYYY-MM-DD format.
length_in_minutes	Integer	The length of time required for the job, in minutes
job_type_id	Integer	A valid job type ID
users optional	Array	An array of user IDs that you want to schedule this job for. If this is omitted, all users will be checked.

Success 200

Field	Type	Description
data	Object	An object of results, where the primary property is the date. Below that are multiple objects, where the property is the user ID, and the value is an array of objects with `start` and `end`, showing the available time blocks that match the criteria.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "2016-09-16": {
      "1": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "15:47:00"
        },
        {
          "start": "16:02:00",
          "end": "17:20:00"
        },
        {
          "start": "18:20:00",
          "end": "21:00:00"
        }
      ],
      "2": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "16:56:00"
        },
        {
          "start": "17:26:00",
          "end": "21:00:00"
        }
      ]
    }
  }
}

Jobs - Find any available space for a job

https://example.sonar.software/api/v1/scheduling/jobs/find_any_available_space

Parameter

Field	Type	Description
start_date	DateTime	The start date for the date range in YYYY-MM-DD format.
end_date	DateTime	The end date for the date range in YYYY-MM-DD format.
length_in_minutes	Integer	The length of time required for the job, in minutes
job_type_id	Integer	A valid job type ID
users optional	Array	An array of user IDs that you want to schedule this job for. If this is omitted, all users will be checked.

Success 200

Field	Type	Description
data	Object	An object of results, where the primary property is the date. Below that are multiple objects, where the property is the user ID, and the value is an array of objects with `start` and `end`, showing the available time blocks that match the criteria.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "2016-09-16": {
      "1": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "15:47:00"
        },
        {
          "start": "16:02:00",
          "end": "17:20:00"
        },
        {
          "start": "18:20:00",
          "end": "21:00:00"
        }
      ],
      "2": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "16:56:00"
        },
        {
          "start": "17:26:00",
          "end": "21:00:00"
        }
      ]
    }
  }
}

Jobs - Find compound available space for a job

Return available blocks of time for a job. You can use this to quickly find available time blocks for a job of a specific length in a date range that you want to schedule for a specific user or group of users. This data is compounded by all the users entered (e.g. if you submit 3 user IDs, it will only return time where all three of those users are available to perform a job of the type submitted.)

https://example.sonar.software/api/v1/scheduling/jobs/find_available_space

Parameter

Field	Type	Description
start_date	DateTime	The start date for the date range in YYYY-MM-DD format.
end_date	DateTime	The end date for the date range in YYYY-MM-DD format.
length_in_minutes	Integer	The length of time required for the job, in minutes
job_type_id	Integer	A valid job type ID
users	Array	An array of user IDs that you want to schedule this job for. You can include a single ID if you want to schedule for a single user.
entityType	String	One of `account` or `network_site`. This is to limit results to entries that meet any defined geofences.
entityId	Integer	The ID of an `account` or `network_site`. This is to limit results to entries that meet any defined geofences.

Success 200

Field	Type	Description
data	Object	An object of results, where the primary property is the date, and the value is an array of objects with `start` and `end`, showing the available time blocks that match the criteria.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "2016-09-16": [
      {
        "start": "04:00:00",
        "end": "10:00:00"
      },
      {
        "start": "15:19:00",
        "end": "16:56:00"
      },
      {
        "start": "18:20:00",
        "end": "21:00:00"
      }
    ],
    "2016-09-18": [
      {
        "start": "00:00:00",
        "end": "01:00:00"
      }
    ],
    "2016-09-19": [
      {
        "start": "00:00:00",
        "end": "21:00:00"
      }
    ]
  }
}

Jobs - Find compound available space for a job

https://example.sonar.software/api/v1/scheduling/jobs/find_available_space

Parameter

Field	Type	Description
start_date	DateTime	The start date for the date range in YYYY-MM-DD format.
end_date	DateTime	The end date for the date range in YYYY-MM-DD format.
length_in_minutes	Integer	The length of time required for the job, in minutes
job_type_id	Integer	A valid job type ID
users	Array	An array of user IDs that you want to schedule this job for. You can include a single ID if you want to schedule for a single user.

Success 200

Field	Type	Description
data	Object	An object of results, where the primary property is the date, and the value is an array of objects with `start` and `end`, showing the available time blocks that match the criteria.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "2016-09-16": [
      {
        "start": "04:00:00",
        "end": "10:00:00"
      },
      {
        "start": "15:19:00",
        "end": "16:56:00"
      },
      {
        "start": "18:20:00",
        "end": "21:00:00"
      }
    ],
    "2016-09-18": [
      {
        "start": "00:00:00",
        "end": "01:00:00"
      }
    ],
    "2016-09-19": [
      {
        "start": "00:00:00",
        "end": "21:00:00"
      }
    ]
  }
}

Jobs - Find compound available space for a job

https://example.sonar.software/api/v1/scheduling/jobs/find_available_space

Parameter

Field	Type	Description
start_date	DateTime	The start date for the date range in YYYY-MM-DD format.
end_date	DateTime	The end date for the date range in YYYY-MM-DD format.
length_in_minutes	Integer	The length of time required for the job, in minutes
job_type_id	Integer	A valid job type ID
users	Array	An array of user IDs that you want to schedule this job for. You can include a single ID if you want to schedule for a single user.

Success 200

Field	Type	Description
data	Object	An object of results, where the primary property is the date, and the value is an array of objects with `start` and `end`, showing the available time blocks that match the criteria.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "2016-09-16": [
      {
        "start": "04:00:00",
        "end": "10:00:00"
      },
      {
        "start": "15:19:00",
        "end": "16:56:00"
      },
      {
        "start": "18:20:00",
        "end": "21:00:00"
      }
    ],
    "2016-09-18": [
      {
        "start": "00:00:00",
        "end": "01:00:00"
      }
    ],
    "2016-09-19": [
      {
        "start": "00:00:00",
        "end": "21:00:00"
      }
    ]
  }
}

Jobs - Get all desired job date/times

Get all desired job date/times for a job

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the job

Success 200

Field	Type	Description
id	Number	The ID of the desired job date/time.
date	Date	The date, in Y-m-d format
start_time	Time	The start time of the time range, in H:m:s format (24 hour)
end_time	Time	The end time of the time range, in H:m:s format (24 hour)

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "date": "2016-09-01",
      "start_time": "07:00:00",
      "end_time": "09:00:00"
    },
    {
      "id": 2,
      "date": "2016-10-01",
      "start_time": "09:00:00",
      "end_time": "11:30:00"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Jobs - Get all jobs

Get all jobs

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
completed_at	DateTime	The date and time the job was completed, if it is complete.
completed_by_user_id	Integer	The ID of the user that completed the job, if it is complete.
completed_successfully	Boolean	If the job is complete, this will be `true` or `false` to show if the job was completed successfully.
completion_reason	String	The reason given upon job completion, if the job is complete.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
       "id": 8,
       "scheduled_datetime": null,
       "job_type_id": 1,
       "length_in_minutes": 60,
       "ticket_id": null,
       "assigned_type": "accounts",
       "assigned_id": 1,
       "notes": "Please replace the router.",
       "status": "queued",
       "user_ids": [],
       "created_by_user_id": 1,
       "checked_in_users": [],
       "services": [] ,
        "completed_at": null,
        "completed_by_user_id": null,
        "completed_successfully": null,
        "completion_reason": null
     }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Jobs - Get all jobs

Get all jobs

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
       "id": 8,
       "scheduled_datetime": null,
       "job_type_id": 1,
       "length_in_minutes": 60,
       "ticket_id": null,
       "assigned_type": "accounts",
       "assigned_id": 1,
       "notes": "Please replace the router.",
       "status": "queued",
       "user_ids": [],
       "created_by_user_id": 1,
       "checked_in_users": [],
       "services": []
     }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Jobs - Get all jobs

Get all jobs

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
       "id": 8,
       "scheduled_datetime": null,
       "job_type_id": 1,
       "length_in_minutes": 60,
       "ticket_id": null,
       "assigned_type": "accounts",
       "assigned_id": 1,
       "notes": "Please replace the router.",
       "status": "queued",
       "user_ids": [],
       "created_by_user_id": 1,
       "checked_in_users": [],
       "services": []
     }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Jobs - Get an individual desired job date/time

Get an individual desired job date/time

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes/:desired_job_datetime_id

Parameter

Field	Type	Description
id	Number	The ID of the job
desired_job_datetime_id	Number	The ID of the desired job date/time

Success 200

Field	Type	Description
id	Number	The ID of the desired job date/time.
date	Date	The date, in Y-m-d format
start_time	Time	The start time of the time range, in H:m:s format (24 hour)
end_time	Time	The end time of the time range, in H:m:s format (24 hour)

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "date": "2016-09-01",
    "start_time": "07:00:00",
    "end_time": "09:00:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Get an individual job

Get an individual job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field	Type	Description
id	Number	The ID of the job

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
completed_at	DateTime	The date and time the job was completed, if it is complete.
completed_by_user_id	Integer	The ID of the user that completed the job, if it is complete.
completed_successfully	Boolean	If the job is complete, this will be `true` or `false` to show if the job was completed successfully.
completion_reason	String	The reason given upon job completion, if the job is complete.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 8,
     "scheduled_datetime": null,
     "job_type_id": 1,
     "length_in_minutes": 60,
     "ticket_id": null,
     "assigned_type": "accounts",
     "assigned_id": 1,
     "notes": "Please replace the router.",
     "status": "queued",
     "user_ids": [],
     "created_by_user_id": 1,
     "checked_in_users": [],
     "services": [] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Get an individual job

Get an individual job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field	Type	Description
id	Number	The ID of the job

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 8,
     "scheduled_datetime": null,
     "job_type_id": 1,
     "length_in_minutes": 60,
     "ticket_id": null,
     "assigned_type": "accounts",
     "assigned_id": 1,
     "notes": "Please replace the router.",
     "status": "queued",
     "user_ids": [],
     "created_by_user_id": 1,
     "checked_in_users": [],
     "services": []
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Get an individual job

Get an individual job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field	Type	Description
id	Number	The ID of the job

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user who created this job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 8,
     "scheduled_datetime": null,
     "job_type_id": 1,
     "length_in_minutes": 60,
     "ticket_id": null,
     "assigned_type": "accounts",
     "assigned_id": 1,
     "notes": "Please replace the router.",
     "status": "queued",
     "user_ids": [],
     "created_by_user_id": 1,
     "checked_in_users": [],
     "services": []
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Return a job to the queue

Move a job back into the queue. This will take a scheduled or failed job, and put it back into the queue.

https://example.sonar.software/api/v1/scheduling/jobs/:id/queue

Parameter

Field	Type	Description
id	Number	The job ID

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
completed_at	DateTime	The date and time the job was completed, if it is complete.
completed_by_user_id	Integer	The ID of the user that completed the job, if it is complete.
completed_successfully	Boolean	If the job is complete, this will be `true` or `false` to show if the job was completed successfully.
completion_reason	String	The reason given upon job completion, if the job is complete.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": [] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Return a job to the queue

Move a job back into the queue. This will take a scheduled or failed job, and put it back into the queue.

https://example.sonar.software/api/v1/scheduling/jobs/:id/queue

Parameter

Field	Type	Description
id	Number	The job ID

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Return a job to the queue

Move a job back into the queue. This will take a scheduled or failed job, and put it back into the queue.

https://example.sonar.software/api/v1/scheduling/jobs/:id/queue

Parameter

Field	Type	Description
id	Number	The job ID

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Update desired job date/time

Update an existing desired job date/time.

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes/:desired_job_datetime_id

Parameter

Field	Type	Description
id	Number	The job ID
desired_job_datetime_id	NUmber	The ID of the desired job date/time
date optional	Date	The date, in Y-m-d format
start_time optional	Time	The start time of the time range, in H:m:s format (24 hour)
end_time optional	Time	The end time of the time range, in H:m:s format (24 hour)

Success 200

Field	Type	Description
id	Number	The ID of the desired job date/time.
date	Date	The date, in Y-m-d format
start_time	Time	The start time of the time range, in H:m:s format (24 hour)
end_time	Time	The end time of the time range, in H:m:s format (24 hour)

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "date": "2016-09-01",
    "start_time": "07:00:00",
    "end_time": "11:45:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Update job

Update an existing job. You can use this to reschedule an already scheduled job, or to schedule a queued job as well.

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field	Type	Description
assigned_type optional	String	The entity you are assigning this job to. This is required if you input `assigned_id`. Allowed values: `"accounts"`, `"network_sites"`
assigned_id optional	Number	The ID of the entity. This is required if you input `assigned_type`.
length_in_minutes optional	Number	The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.
notes optional	String	Any notes for the job.
scheduled_datetime optional	DateTime	If you want to schedule this job now, input a date/time to schedule it for. `user_ids` is required if this is submitted. The timezone should be the timezone of this Sonar instance.
user_ids optional	Array	Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. This will be ignored if the job is not currently scheduled, or you do not submit a `scheduled_datetime`.
services optional	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
ticket_id	Integer	ID of a ticket that this job is linked to. If `null` is sent, the job will not be linked to a ticket.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
completed_at	DateTime	The date and time the job was completed, if it is complete.
completed_by_user_id	Integer	The ID of the user that completed the job, if it is complete.
completed_successfully	Boolean	If the job is complete, this will be `true` or `false` to show if the job was completed successfully.
completion_reason	String	The reason given upon job completion, if the job is complete.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 22,
    "scheduled_datetime": "2016-08-29 11:00",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Replace the Cisco router with a Juniper router.",
    "status": "scheduled",
    "user_ids": [
      1
    ],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": [] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Update job

Update an existing job. You can use this to reschedule an already scheduled job, or to schedule a queued job as well.

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field	Type	Description
assigned_type optional	String	The entity you are assigning this job to. This is required if you input `assigned_id`. Allowed values: `"accounts"`, `"network_sites"`
assigned_id optional	Number	The ID of the entity. This is required if you input `assigned_type`.
length_in_minutes optional	Number	The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.
notes optional	String	Any notes for the job.
scheduled_datetime optional	DateTime	If you want to schedule this job now, input a date/time to schedule it for. `user_ids` is required if this is submitted. The timezone should be the timezone of this Sonar instance.
user_ids optional	Array	Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. This will be ignored if the job is not currently scheduled, or you do not submit a `scheduled_datetime`.
services optional	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.
ticket_id	Integer	ID of a ticket that this job is linked to. If `null` is sent, the job will not be linked to a ticket.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 22,
    "scheduled_datetime": "2016-08-29 11:00",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Replace the Cisco router with a Juniper router.",
    "status": "scheduled",
    "user_ids": [
      1
    ],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Update job

Update an existing job. You can use this to reschedule an already scheduled job, or to schedule a queued job as well.

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field	Type	Description
job_type_id optional	Number	The ID of a job type
assigned_type optional	String	The entity you are assigning this job to. This is required if you input `assigned_id`. Allowed values: `"accounts"`, `"network_sites"`
assigned_id optional	Number	The ID of the entity. This is required if you input `assigned_type`.
length_in_minutes optional	Number	The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.
notes optional	String	Any notes for the job.
scheduled_datetime optional	DateTime	If you want to schedule this job now, input a date/time to schedule it for. `user_ids` is required if this is submitted. The timezone should be the timezone of this Sonar instance.
user_ids optional	Array	Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. This will be ignored if the job is not currently scheduled, or you do not submit a `scheduled_datetime`.
services optional	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success 200

Field	Type	Description
id	Number	The ID of the job.
scheduled_datetime	DateTime	When the job is scheduled for, in the timezone of this Sonar instance.
job_type_id	Number	The ID of the job type
length_in_minutes	Number	The time allotted for the job
ticket_id	Number	The ID of a ticket this job is associated with
assigned_type	String	The entity this job is assigned to Allowed values: `"accounts"`, `"network_sites"`
assigned_id	Number	The ID of the entity this job is assigned to
notes	String	Some notes for the job
status	String	The current status of the job Allowed values: `"queued"`, `"scheduled"`, `"failed"`, `"completed"`
user_ids	Array	An array of user IDs that are assigned to complete this job.
created_by_user_id	Integer	The ID of the user that created the job
checked_in_users	Array	An array of arrays, where the internal arrays have an integer of `user_id` for the user ID that is checked in, and an UTC date/time of `datetime` for the date and time they checked in.
services	Array	An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 22,
    "scheduled_datetime": "2016-08-29 11:00",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Replace the Cisco router with a Juniper router.",
    "status": "scheduled",
    "user_ids": [
      1
    ],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Mapping

Mapping - Get GeoJSON data

Get GeoJSON for specific data inside Sonar. This can be used to display your geographical data on an external map. This data is cached, and only updates once every minute.

https://example.sonar.software/api/v1/mapping/geojson/:type

Parameter

Field Type Description

type

String

The type of data to get.

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles"

Success 200

Field	Type	Description
data	Object	Returns data in GeoJSON format - documented at http://geojson.org/. Each type returns different properties that are relevant to the type being returned. The vehicles endpoint returns a MultiPoint feature, which shows the last 100 points tracked for the vehicle. Vehicle data is only available if you have enabled GPS tracking inside Sonar. The most current location is the first element in the array.

 HTTP/1.1 200 OK
 {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -80.33397,
            39.96938
          ]
        },
        "properties": {
          "id": 1,
          "name": "Some Test Account",
          "account_type": "Residential",
          "account_status": "Active",
          "status_color": "#3498db"
        }
      },
      {
        "type": "feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -106.53,
            34.591
          ]
        },
        "properties": {
          "id": 2,
          "name": "Prof. Luna O'Hara V",
          "account_type": "Commercial",
          "account_status": "Lead",
          "status_color": "#9b59b6"
        }
      }
    ]
}

 HTTP/1.1 200 OK
 {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -85.34969,
            42.289
          ],
          [
            -85.34969,
            42.289
          ],
          [
            -85.34969,
            42.289
          ]
        ]
      },
      "properties": {
        "id": 1,
        "name": "My Test Vehicle",
        "manufacturer": "Ford",
        "model": "F150",
        "year": 2009,
        "license_plate": "12345",
        "vin": "ABC123",
        "other_data": {
          "Name": "Steve-(16)",
          "Status": "Key Off (IS)"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -84.48617,
            42.2381
          ],
          [
            -84.31253,
            42.2381
          ]
        ]
      },
      "properties": {
        "id": 2,
        "name": "Another Vehicle",
        "manufacturer": "Chevrolet",
        "model": "Camaro",
        "year": 2008,
        "license_plate": "1234512345",
        "vin": "ABCDEFG",
        "other_data": {
          "Name": "Roger Steele (13)",
          "Status": "Key On (IS)"
        }
      }
    }
  ]
}

Mapping - Get GeoJSON data

Get GeoJSON for specific data inside Sonar. This can be used to display your geographical data on an external map. This data is cached, and only updates once every minute.

https://example.sonar.software/api/v1/mapping/geojson/:type

Parameter

Field Type Description

type

String

The type of data to get.

Allowed values: "accounts", "network_sites", "inventory_locations"

Success 200

Field	Type	Description
data	Object	Returns data in GeoJSON format - documented at http://geojson.org/. Each type returns different properties that are relevant to the type being returned.

Success-Response (Accounts):

 HTTP/1.1 200 OK
 {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -80.33397,
            39.96938
          ]
        },
        "properties": {
          "id": 1,
          "name": "Some Test Account",
          "account_type": "Residential",
          "account_status": "Active",
          "status_color": "#3498db"
        }
      },
      {
        "type": "feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -106.53,
            34.591
          ]
        },
        "properties": {
          "id": 2,
          "name": "Prof. Luna O'Hara V",
          "account_type": "Commercial",
          "account_status": "Lead",
          "status_color": "#9b59b6"
        }
      }
    ]
}

Mapping - Get a mapping of network sites, inventory items, and subscriber IPs

Retrieve a mapping of network data, pulled using the Sonar poller. This endpoint is explicitly in place to enable integration with external systems. The data is keyed by network site ID and inventory item ID respectively, to make integration with external systems easier.

https://example.sonar.software/api/v1/network/mapping

Success 200

Field	Type	Description
id	Integer	The ID of the network site
name	String	The name of the network site
inventory_items	Object	An object containing inner objects, keyed by the inventory item ID, representing the inventory items deployed at this network site. The lines below describe the content of each inventory item object.
category	String	The model category of the inventory item
model_name	String	The model name of the inventory item
ip_description	String	The description of the IP address assigned to the device, if there is one.
merged_description	String	A human friendly description that can be used for the device.
ip_address	String	The IP address of the inventory item
subscribers	Array	An array of subscriber data (name, id, and an array of IP addressess), for subscribers that are attached to this inventory item.

Success-Response:

 HTTP/1.1 201 OK
 {
     "data": {
         "1": {
             "id": 1,
             "name": "A-002 DeBolt",
             "inventory_items": {
                 "2531": {
                     "id": 2531,
                     "category": "Access Points",
                     "model_name": "PMP 450 3.6 Ghz AP",
                     "ip_address": "172.20.1.10",
                     "ip_description": "A-002-36450AP-01",
                     "merged_description": "PMP 450 3.6 Ghz AP (172.20.1.10) - A-002-36450AP-01",
                     "subscriber_data": [],
                     "subscribers": {
                         "28": {
                             "name": "Tom & Alisa Burton",
                             "id": 28,
                             "ips": [
                                 "10.1.1.33/32",
                             ]
                         },
                         "35": {
                             "name": "Ellen Moore",
                             "id": 35,
                             "ips": [
                                 "10.1.1.89/32",
                             ]
                         },
                         "47": {
                             "name": "Jason Moody",
                             "id": 47,
                             "ips": [
                                 "10.1.1.57/32",
                                 "192.168.82.35/32"
                             ]
                         },
                         "49": {
                             "name": "828859 Alberta Ltd",
                             "id": 49,
                             "ips": [
                                 "10.1.1.50/32"
                             ]
                         }
                    }
            }
        }
    }
}

Monitoring Data

Monitoring_Data - Get monitoring data

Get monitoring data, between start_date and end_date for inventory item with ID inventory_item_id, as long as it was assigned to entity with entity_id. The results for this are in a fairly complex structure, and are meant to be used for inclusion in external data display systems.

https://example.sonar.software/api/v1/network/monitoring/monitoring_data/{entity}/{entity_id}/inventory_items/{inventory_item_id}/{start_date}/{end_date}

Parameter

Field	Type	Description
entity	String	The entity Allowed values: `"accounts"`, `"network_sites"`
entity_id	Integer	The ID of the entity
inventory_item_id	Integer	The ID of the inventory item that was being monitored
start_date	Date	The start date, in YYYY-MM-DD format
end_date	Date	The end date, in YYYY-MM-DD format

Success 200

Field	Type	Description
template_details	Object	An object containing details on the template that has been used to control the data to monitor. See the monitoring templates section for more details.
status	Object	This object contains two arrays, `snmp` and `icmp`. Each array contains multiple arrays with three values. The first is a unix timestamp for when the data was retrieved. The second is an integer, 0 means down, 1 means warning, and 2 means good. The third is an optional string that will describe the reason the device is in down or warning.
snmp	Object	This object contains the results for all the SNMP OIDs defined in `template_details`. Each property in this object is the ID of an SNMP OID. The value is an array of arrays, where each array contains two values. The first value is the unix timestamp when the data was collected. The second value is the value collected.
icmp	Array	This array contains the results for any ICMP monitoring performed. There are multiple arrays contained within, each with 5 values. The first value is the unix timestamp when the data was collected. The next four values are the lowest latency value, the median latency value, the maximum latency value, and the packet loss percentage for that timestamp.
interfaces	Object	This object contains the latest interface details for each interface being monitored. Each property in this object is the name of the interface being monitored. Each property has an associated object, which contains a list of standard Ethernet MIB names, and then an array of arrays, which will only contain a single array with the most current value in it. The first value in the array is a unix timestamp of when the data was collected, and the second value is the actual data collected.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "template_details": {
      "name": "MikroTik",
      "icmp_latency_threshold": 500,
      "icmp_loss_threshold": 50,
      "icmp": true,
      "collect_interface_statistics": true,
      "graphs": {
        "15": {
          "type": "line",
          "stacked": false,
          "name": "Memory"
        }
      },
      "snmp_oids": {
        "17": {
          "id": 17,
          "name": "Total Memory",
          "color": "#1abc9c",
          "unit_of_measurement": "MB",
          "graph_id": 15,
          "oid": "1.3.6.1.2.1.25.2.3.1.5.65536",
          "thresholds": [

          ]
        },
        "16": {
          "id": 16,
          "name": "Used Memory",
          "color": "#e74c3c",
          "unit_of_measurement": "MB",
          "graph_id": 15,
          "oid": "1.3.6.1.2.1.25.2.3.1.6.65536",
          "thresholds": [

          ]
        },
        "15": {
          "id": 15,
          "name": "CPU Usage",
          "color": "#e74c3c",
          "unit_of_measurement": "%",
          "graph_id": null,
          "oid": "1.3.6.1.2.1.25.3.3.1.2.1",
          "thresholds": [
            {
              "operator": "gte",
              "value": "50",
              "time_period_in_minutes": 15
            }
          ]
        }
      }
    },
    "status": {
      "snmp": [
        [
          1481041629,
          2,
          ""
        ],
        [
          1481041716,
          2,
          ""
        ],
        [
          1481041803,
          2,
          ""
        ],
        [
          1481041890,
          2,
          ""
        ],
        [
          1481041977,
          2,
          ""
        ],
        [
          1481042064,
          2,
          ""
        ],
        [
          1481042151,
          2,
          ""
        ],
        [
          1481042238,
          2,
          ""
        ],
        [
          1481042325,
          2,
          ""
        ],
        [
          1481042412,
          2,
          ""
        ],
        [
          1481042499,
          2,
          ""
        ],
        [
          1481042586,
          2,
          ""
        ],
        [
          1481042673,
          2,
          ""
        ],
        [
          1481042760,
          2,
          ""
        ]
      ],
      "icmp": [
        [
          1481041629,
          2,
          ""
        ],
        [
          1481041716,
          2,
          ""
        ],
        [
          1481041803,
          2,
          ""
        ],
        [
          1481041890,
          2,
          ""
        ],
        [
          1481041977,
          2,
          ""
        ],
        [
          1481042064,
          2,
          ""
        ],
        [
          1481042151,
          2,
          ""
        ],
        [
          1481042238,
          2,
          ""
        ],
        [
          1481042325,
          2,
          ""
        ],
        [
          1481042412,
          2,
          ""
        ],
        [
          1481042499,
          2,
          ""
        ],
        [
          1481042586,
          2,
          ""
        ],
        [
          1481042673,
          2,
          ""
        ],
        [
          1481042760,
          2,
          ""
        ]
      ]
    },
    "snmp": {
      "17": [
        [
          1481041629,
          131072
        ],
        [
          1481041716,
          131072
        ],
        [
          1481041803,
          131072
        ],
        [
          1481041890,
          131072
        ],
        [
          1481041977,
          131072
        ],
        [
          1481042064,
          131072
        ],
        [
          1481042151,
          131072
        ],
        [
          1481042238,
          131072
        ],
        [
          1481042325,
          131072
        ],
        [
          1481042412,
          131072
        ],
        [
          1481042499,
          131072
        ],
        [
          1481042586,
          131072
        ],
        [
          1481042673,
          131072
        ],
        [
          1481042760,
          131072
        ]
      ],
      "16": [
        [
          1481041629,
          34172
        ],
        [
          1481041716,
          34056
        ],
        [
          1481041803,
          34088
        ],
        [
          1481041890,
          34024
        ],
        [
          1481041977,
          34024
        ],
        [
          1481042064,
          34024
        ],
        [
          1481042151,
          34024
        ],
        [
          1481042238,
          34008
        ],
        [
          1481042325,
          34024
        ],
        [
          1481042412,
          34072
        ],
        [
          1481042499,
          34072
        ],
        [
          1481042586,
          34064
        ],
        [
          1481042673,
          34024
        ],
        [
          1481042760,
          34032
        ]
      ],
      "15": [
        [
          1481041629,
          2
        ],
        [
          1481041716,
          2
        ],
        [
          1481041803,
          2.5
        ],
        [
          1481041890,
          2
        ],
        [
          1481041977,
          2.5
        ],
        [
          1481042064,
          0
        ],
        [
          1481042151,
          1
        ],
        [
          1481042238,
          3
        ],
        [
          1481042325,
          11
        ],
        [
          1481042412,
          2
        ],
        [
          1481042499,
          3
        ],
        [
          1481042586,
          3
        ],
        [
          1481042673,
          3
        ],
        [
          1481042760,
          6.5
        ]
      ]
    },
    "icmp": [
      [
        1481041629,
        0.42,
        0.46,
        0.5,
        0
      ],
      [
        1481041716,
        0.44,
        0.49,
        0.98,
        0
      ],
      [
        1481041803,
        0.41,
        0.465,
        0.99,
        0
      ],
      [
        1481041890,
        0.41,
        0.47,
        0.51,
        0
      ],
      [
        1481041977,
        0.39,
        0.495,
        0.56,
        0
      ],
      [
        1481042064,
        0.46,
        0.49,
        0.92,
        0
      ],
      [
        1481042151,
        0.42,
        0.48,
        0.64,
        0
      ],
      [
        1481042238,
        0.41,
        0.47,
        1.01,
        0
      ],
      [
        1481042325,
        0.45,
        0.49,
        0.55,
        0
      ],
      [
        1481042412,
        0.39,
        0.48,
        1.06,
        0
      ],
      [
        1481042499,
        0.44,
        0.47,
        0.65,
        0
      ],
      [
        1481042586,
        0.45,
        0.49,
        0.62,
        0
      ],
      [
        1481042673,
        0.44,
        0.47,
        0.5,
        0
      ],
      [
        1481042760,
        0.43,
        0.475,
        1.08,
        0
      ]
    ],
    "interfaces": {
      "bridge-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            56.545977011494
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            5174.1609195402
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            35.16091954023
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            63527.310344828
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            100000000
          ]
        ],
        "ifType": [
          [
            1481041629,
            209
          ]
        ]
      },
      "ether1-gateway": {
        "IfOutUcastPkts": [
          [
            1481041716,
            27.850574712644
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            56059.454022989
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            134.99425287356
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            5230.4597701149
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            1000000000
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether10-slave-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether2": {
        "IfOutUcastPkts": [
          [
            1481041716,
            22.022988505747
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            4140.9770114943
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            18.816091954023
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            18658.017241379
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            100000000
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether3": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether4": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether5": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether6-master-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether7-slave-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether8-slave-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether9-slave-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "sfp1": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "wlan1": {
        "IfOutUcastPkts": [
          [
            1481041716,
            37.362068965517
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            1800.7011494253
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            17.844827586207
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            45367.350574713
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            11000000
          ]
        ],
        "ifType": [
          [
            1481041629,
            71
          ]
        ]
      }
    }
  }
}

Monitoring Templates

Monitoring_Templates - Create a new SNMP OID threshold

Create a new SNMP OID threshold. Defining thresholds allows you to move a device into a threshold violating status when it crosses a certain boundary. For example, you can define a threshold that CPU usage must remain below 50% by using the operator lt and the value 50 on an SNMP OID that pulls CPU usage.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
snmp_oid_id	Integer	The ID of the SNMP OID
operator	String	The operator to use when evaluating the current result against the threshold defined. `gt` is greater than, `gte` is greater than or equal to, `lt` is less than, `lte` is less than or equal to, `eq` is equal to and `neq` is not equal to. Allowed values: `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"eq"`, `"neq"`
value	String	The value to use for the threshold. If the value is a string, then only `eq` or `neq` are allowed as operators.
time_period_in_minutes	Integer	The amount of time that the threshold must be violated before it is triggered

Success 200

Field	Type	Description
id	Integer	The ID of the SNMP OID threshold.
operator	String	The operator to use when evaluating the current result against the threshold defined. `gt` is greater than, `gte` is greater than or equal to, `lt` is less than, `lte` is less than or equal to, `eq` is equal to and `neq` is not equal to. Allowed values: `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"eq"`, `"neq"`
value	String	The value to use for the threshold. If the value is a string, then only `eq` or `neq` are allowed as operators.
time_period_in_minutes	Integer	The amount of time that the threshold must be violated before it is triggered

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "operator": "lt",
    "value": 5,
    "time_period_in_minutes": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "That SNMP OID does not exist.",
     "status_code": 404
   }
 }

Monitoring_Templates - Create a new SNMP OID

Create a new SNMP OID.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template to add this OID to.
name	String	A name for the SNMP OID
oid	String	A numeric OID
color optional	String	A hex color code for the SNMP OID. This will define the color used when graphing this OID. Default value: `#3498db`
unit_of_measurement optional	String	The unit of measurement for the SNMP OID (e.g. `bytes`, `%`, `Fahrenheit`.)
monitoring_graph_id optional	Integer	If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.
auto_scale optional	Boolean	Whether or not to automatically scale this OID in thousands. Default value: `false`
display_as_table optional	Boolean	If this is `true`, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs. Default value: `false`

Success 200

Field	Type	Description
id	Number	The ID of the SNMP OID.
name	String	The name of the SNMP OID
oid	String	The numeric OID
color	String	A hex color code for the SNMP OID. This will define the color used when graphing this OID. Default value: `#3498db`
unit_of_measurement	String	The unit of measurement for the SNMP OID (e.g. `bytes`, `%`, `Fahrenheit`.)
monitoring_graph_id	Integer	If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.
auto_scale	Boolean	Whether or not results from this OID are automatically scaled by thousands.
display_as_table	Boolean	If this is `true`, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "oid": "1.2.3.4",
    "name": "Test",
    "color": "#3498db",
    "unit_of_measurement": null,
    "monitoring_graph_id": null,
    "auto_scale": false,
    "display_as_table": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "oid": "The oid has already been taken."
     },
     "status_code": 422
   }
 }

Monitoring_Templates - Create a new monitoring graph

Create a new monitoring graph. This is a graph definition that can be associated with multiple SNMP OIDs, in order to graph multiple results on a single graph.

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template this graph will be available for
name	String	A name for the monitoring graph
type	String	The type of graph Allowed values: `"line"`, `"bar"`, `"area"`
stacked	Boolean	Whether or not values should be stacked on the graph, or drawn independently Default value: `false`

Success 200

Field	Type	Description
id	Integer	The ID of the monitoring graph.
name	String	The name of the monitoring graph
type	String	The type of graph
stacked	Boolean	Whether or not values should be stacked on the graph, or drawn independently

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "Aggregate Graph",
    "type": "line",
    "stacked": false
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "type": "The selected type is invalid."
     },
     "status_code": 422
   }
 }

Monitoring_Templates - Create a new monitoring template

Create a new monitoring template. A monitoring template is a template that defines items to monitor on an inventory model.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates

Example

{
     "name": "Standard CPE Template",
     "snmp_version": 2,
     "snmp_community": "public",
     "icmp": false,
     "collect_interface_statistics": true,
     "inventory_model_ids": [
          1,
          2,
          5
     ]
}

Parameter

Field	Type	Description
name	String	A name for the monitoring template
snmp_version optional	Integer	Default SNMP queries made using this template to this SNMP version. `2` is version 2c. Allowed values: `1`, `2`, `3`
snmp_community optional	String	Default SNMP queries made using this template to use this SNMP community. If your `snmp_version` is `3`, then this will be used as the SNMPv3 securityName.
snmp3_sec_level optional	String	If you are using SNMPv3, this is the default security level Allowed values: `"noAuthNoPriv"`, `"authNoPriv"`, `"authPriv"`
snmp3_auth_protocol optional	String	If you are using SNMPv3, this is the default authentication protocol Allowed values: `"MD5"`, `"SHA"`
snmp3_auth_passphrase optional	String	If you are using SNMPv3, this is the default authentication pass phrase
snmp3_priv_protocol optional	String	If you are using SNMPv3, this is the default privacy protocol Allowed values: `"DES"`, `"AES"`
snmp3_priv_passphrase optional	String	If you are using SNMPv3, this is the default privacy passphrase
snmp3_context_name optional	String	If you are using SNMPv3, this is the default context name
snmp3_context_engine_id optional	String	If you are using SNMPv3, this is the default context EngineID
icmp optional	Boolean	Whether or not to perform ICMP monitoring Default value: `false`
icmp_latency_threshold optional	Integer	If this is set, then a median latency above this value will put a device into warning status
icmp_loss_threshold optional	Integer	If this is set, then a packet loss percentage above this value will put the device into warning status
collect_interface_statistics optional	Boolean	Whether or not to collect interface statistics Default value: `false`
inventory_model_ids optional	Array	An array of inventory model IDs that should have this monitoring template applied to them.

Success 200

Field	Type	Description
id	Number	The ID of the monitoring template.
name	String	The name of the monitoring template
inventory_model_ids	Array	An array of inventory model IDs that have this monitoring template applied to them.
snmp_version	Integer	Default SNMP queries made using this template to this SNMP version. `2` is version 2c. Allowed values: `1`, `2`, `3`
snmp_community	String	Default SNMP queries made using this template to use this SNMP community. If your `snmp_version` is `3`, then this will be used as the SNMPv3 securityName.
snmp3_sec_level	String	If you are using SNMPv3, this is the default security level Allowed values: `"noAuthNoPriv"`, `"authNoPriv"`, `"authPriv"`
snmp3_auth_protocol	String	If you are using SNMPv3, this is the default authentication protocol Allowed values: `"MD5"`, `"SHA"`
snmp3_auth_passphrase	String	If you are using SNMPv3, this is the default authentication pass phrase
snmp3_priv_protocol	String	If you are using SNMPv3, this is the default privacy protocol Allowed values: `"DES"`, `"AES"`
snmp3_priv_passphrase	String	If you are using SNMPv3, this is the default privacy passphrase
snmp3_context_name	String	If you are using SNMPv3, this is the default context name
snmp3_context_engine_id	String	If you are using SNMPv3, this is the default context EngineID
icmp	Boolean	Whether or not to perform ICMP monitoring
collect_interface_statistics	Boolean	Whether or not to collect interface statistics Default value: `false`

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Standard CPE Template",
    "snmp_version": 2,
    "snmp_community": "public",
    "snmp3_sec_level": null,
    "snmp3_auth_protocol": null,
    "snmp3_auth_passphrase": null,
    "snmp3_priv_protocol": null,
    "snmp3_priv_passphrase": null,
    "snmp3_context_name": null,
    "snmp3_context_engine_id": null,
    "icmp": false,
    "collect_interface_statistics": true,
    "inventory_model_ids": [
         1,
         2,
         5
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "icmp": "icmp must be a boolean."
     },
     "status_code": 422
   }
 }

Monitoring_Templates - Delete a SNMP OID threshold

Delete a SNMP OID threshold

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
snmp_oid_id	Integer	The ID of the SNMP oid
id	Integer	The ID of the SNMP OID threshold

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the SNMP OID threshold could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "SNMP OID threshold does not exist.",
         "status_code": 404
     }
 }

Monitoring_Templates - Delete a SNMP OID

Delete a SNMP OID

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
id	Integer	The ID of the SNMP OID

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the SNMP OID could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "SNMP OID does not exist.",
         "status_code": 404
     }
 }

Monitoring_Templates - Delete a monitoring graph

Delete a monitoring graph

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
id	Integer	The ID of the monitoring graph

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the monitoring graph could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "monitoring graph does not exist.",
         "status_code": 404
     }
 }

Monitoring_Templates - Delete a monitoring template

Delete a monitoring template

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:id

Parameter

Field	Type	Description
id	Number	The ID of the monitoring template

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the monitoring template could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "monitoring template does not exist.",
         "status_code": 404
     }
 }

Monitoring_Templates - Get all SNMP OID thresholds

Get all SNMP OID thresholds.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
snmp_oid_id	Integer	The ID of the SNMP oid
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the SNMP OID threshold.
operator	String	The operator to use when evaluating the current result against the threshold defined. `gt` is greater than, `gte` is greater than or equal to, `lt` is less than, `lte` is less than or equal to, `eq` is equal to and `neq` is not equal to. Allowed values: `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"eq"`, `"neq"`
value	String	The value to use for the threshold. If the value is a string, then only `eq` or `neq` are allowed as operators.
time_period_in_minutes	Integer	The amount of time that the threshold must be violated before it is triggered

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "operator": "lt",
      "value": 5,
      "time_period_in_minutes": 15
    },
    {
      "id": 1,
      "operator": "gte",
      "value": 15,
      "time_period_in_minutes": 1
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Monitoring_Templates - Get all SNMP OIDs for a template

Get all SNMP OIDs associated with a particular monitoring template.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the SNMP OID.
name	String	The name of the SNMP OID
oid	String	The numeric OID
color	String	A hex color code for the SNMP OID. This will define the color used when graphing this OID. Default value: `#3498db`
unit_of_measurement	String	The unit of measurement for the SNMP OID (e.g. `bytes`, `%`, `Fahrenheit`.)
monitoring_graph_id	Integer	If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.
auto_scale	Boolean	Whether or not results from this OID are automatically scaled by thousands.
display_as_table	Boolean	If this is `true`, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "oid": "1.2.3.4",
      "name": "Test",
      "color": "#3498db",
      "unit_of_measurement": null,
      "monitoring_graph_id": 2,
      "auto_scale": true,
      "display_as_table": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Monitoring_Templates - Get all monitoring graphs

Get all monitoring graphs

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the monitoring graph.
name	String	The name of the monitoring graph
type	String	The type of graph
stacked	Boolean	Whether or not values should be stacked on the graph, or drawn independently

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Aggregate Graph",
      "type": "line",
      "stacked": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Monitoring_Templates - Get all monitoring templates

Get all monitoring templates

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the monitoring template.
name	String	The name of the monitoring template
inventory_model_ids	Array	An array of inventory model IDs that have this monitoring template applied to them.
snmp_version	Integer	Default SNMP queries made using this template to this SNMP version. `2` is version 2c. Allowed values: `1`, `2`, `3`
snmp_community	String	Default SNMP queries made using this template to use this SNMP community. If your `snmp_version` is `3`, then this will be used as the SNMPv3 securityName.
snmp3_sec_level	String	If you are using SNMPv3, this is the default security level Allowed values: `"noAuthNoPriv"`, `"authNoPriv"`, `"authPriv"`
snmp3_auth_protocol	String	If you are using SNMPv3, this is the default authentication protocol Allowed values: `"MD5"`, `"SHA"`
snmp3_auth_passphrase	String	If you are using SNMPv3, this is the default authentication pass phrase
snmp3_priv_protocol	String	If you are using SNMPv3, this is the default privacy protocol Allowed values: `"DES"`, `"AES"`
snmp3_priv_passphrase	String	If you are using SNMPv3, this is the default privacy passphrase
snmp3_context_name	String	If you are using SNMPv3, this is the default context name
snmp3_context_engine_id	String	If you are using SNMPv3, this is the default context EngineID
icmp	Boolean	Whether or not to perform ICMP monitoring
collect_interface_statistics	Boolean	Whether or not to collect interface statistics Default value: `false`

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "name": "My Test Template",
      "snmp_version": 1,
      "snmp_community": "private",
      "snmp3_sec_level": null,
      "snmp3_auth_protocol": null,
      "snmp3_auth_passphrase": null,
      "snmp3_priv_protocol": null,
      "snmp3_priv_passphrase": null,
      "snmp3_context_name": null,
      "snmp3_context_engine_id": null,
      "icmp": false,
      "icmp_latency_threshold": null,
      "icmp_loss_threshold": null,
      "collect_interface_statistics": false,
      "inventory_model_ids": [
        3
      ]
    },
    {
      "id": 14,
      "name": "MikroTik Probe",
      "snmp_version": 2,
      "snmp_community": "public",
      "snmp3_sec_level": null,
      "snmp3_auth_protocol": null,
      "snmp3_auth_passphrase": null,
      "snmp3_priv_protocol": null,
      "snmp3_priv_passphrase": null,
      "snmp3_context_name": null,
      "snmp3_context_engine_id": null,
      "icmp": true,
      "icmp_latency_threshold": null,
      "icmp_loss_threshold": null,
      "collect_interface_statistics": false,
      "inventory_model_ids": [
           1
      ]
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Monitoring_Templates - Get an individual SNMP OID threshold

Get an individual SNMP OID threshold.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
snmp_oid_id	Integer	The ID of the SNMP oid
id	Integer	The ID of the SNMP OID threshold

Success 200

Field	Type	Description
id	Integer	The ID of the SNMP OID threshold.
operator	String	The operator to use when evaluating the current result against the threshold defined. `gt` is greater than, `gte` is greater than or equal to, `lt` is less than, `lte` is less than or equal to, `eq` is equal to and `neq` is not equal to. Allowed values: `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"eq"`, `"neq"`
value	String	The value to use for the threshold. If the value is a string, then only `eq` or `neq` are allowed as operators.
time_period_in_minutes	Integer	The amount of time that the threshold must be violated before it is triggered

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "operator": "lt",
    "value": 5,
    "time_period_in_minutes": 12
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Get an individual SNMP OID

Get an individual SNMP OID

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
id	Integer	The ID of the SNMP OID

Success 200

Field	Type	Description
id	Number	The ID of the SNMP OID.
name	String	The name of the SNMP OID
oid	String	The numeric OID
color	String	A hex color code for the SNMP OID. This will define the color used when graphing this OID. Default value: `#3498db`
unit_of_measurement	String	The unit of measurement for the SNMP OID (e.g. `bytes`, `%`, `Fahrenheit`.)
monitoring_graph_id	Integer	If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.
auto_scale	Boolean	Whether or not results from this OID are automatically scaled by thousands.
display_as_table	Boolean	If this is `true`, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
      "id": 2,
      "oid": "1.2.3.4",
      "name": "Test",
      "color": "#3498db",
      "unit_of_measurement": null,
      "monitoring_graph_id": 2,
      "auto_scale": true,
      "display_as_table": false
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Get an individual monitoring graph

Get an individual monitoring graph

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
id	Integer	The ID of the monitoring graph

Success 200

Field	Type	Description
id	Integer	The ID of the monitoring graph.
name	String	The name of the monitoring graph
type	String	The type of graph
stacked	Boolean	Whether or not values should be stacked on the graph, or drawn independently

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Aggregate Graph",
    "type": "line",
    "stacked": false
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Get an individual monitoring template

Get an individual monitoring template

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:id

Parameter

Field	Type	Description
id	Number	The ID of the monitoring template

Success 200

Field	Type	Description
id	Number	The ID of the monitoring template.
name	String	The name of the monitoring template
inventory_model_ids	Array	An array of inventory model IDs that have this monitoring template applied to them.
snmp_version	Integer	Default SNMP queries made using this template to this SNMP version. `2` is version 2c. Allowed values: `1`, `2`, `3`
snmp_community	String	Default SNMP queries made using this template to use this SNMP community. If your `snmp_version` is `3`, then this will be used as the SNMPv3 securityName.
snmp3_sec_level	String	If you are using SNMPv3, this is the default security level Allowed values: `"noAuthNoPriv"`, `"authNoPriv"`, `"authPriv"`
snmp3_auth_protocol	String	If you are using SNMPv3, this is the default authentication protocol Allowed values: `"MD5"`, `"SHA"`
snmp3_auth_passphrase	String	If you are using SNMPv3, this is the default authentication pass phrase
snmp3_priv_protocol	String	If you are using SNMPv3, this is the default privacy protocol Allowed values: `"DES"`, `"AES"`
snmp3_priv_passphrase	String	If you are using SNMPv3, this is the default privacy passphrase
snmp3_context_name	String	If you are using SNMPv3, this is the default context name
snmp3_context_engine_id	String	If you are using SNMPv3, this is the default context EngineID
icmp	Boolean	Whether or not to perform ICMP monitoring
collect_interface_statistics	Boolean	Whether or not to collect interface statistics Default value: `false`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "MikroTik Probe",
    "snmp_version": 0,
    "snmp_community": null,
    "snmp3_sec_level": null,
    "snmp3_auth_protocol": null,
    "snmp3_auth_passphrase": null,
    "snmp3_priv_protocol": null,
    "snmp3_priv_passphrase": null,
    "snmp3_context_name": null,
    "snmp3_context_engine_id": null,
    "icmp": true,
    "icmp_latency_threshold": null,
    "icmp_loss_threshold": null,
    "collect_interface_statistics": false,
    "inventory_model_ids": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Update SNMP OID threshold

Update an existing SNMP OID threshold.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
snmp_oid_id	Integer	The ID of the SNMP oid
id	Integer	The ID of the SNMP OID threshold
operator optional	String	The operator to use when evaluating the current result against the threshold defined. `gt` is greater than, `gte` is greater than or equal to, `lt` is less than, `lte` is less than or equal to, `eq` is equal to and `neq` is not equal to. Allowed values: `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"eq"`, `"neq"`
value optional	String	The value to use for the threshold. If the value is a string, then only `eq` or `neq` are allowed as operators.
time_period_in_minutes optional	Integer	The amount of time that the threshold must be violated before it is triggered

Success 200

Field	Type	Description
id	Integer	The ID of the SNMP OID threshold.
operator	String	The operator to use when evaluating the current result against the threshold defined. `gt` is greater than, `gte` is greater than or equal to, `lt` is less than, `lte` is less than or equal to, `eq` is equal to and `neq` is not equal to. Allowed values: `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"eq"`, `"neq"`
value	String	The value to use for the threshold. If the value is a string, then only `eq` or `neq` are allowed as operators.
time_period_in_minutes	Integer	The amount of time that the threshold must be violated before it is triggered

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "operator": "lt",
    "value": 5,
    "time_period_in_minutes": 15
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Update SNMP OID

Update an existing SNMP OID.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template to add this OID to.
id	Integer	The ID of the SNMP OID
name	String	A name for the SNMP OID
oid	String	A numeric OID
color optional	String	A hex color code for the SNMP OID. This will define the color used when graphing this OID. Default value: `#3498db`
unit_of_measurement optional	String	The unit of measurement for the SNMP OID (e.g. `bytes`, `%`, `Fahrenheit`.)
monitoring_graph_id optional	Integer	If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.
auto_scale optional	Boolean	Whether or not to automatically scale this OID in thousands. Default value: `false`
display_as_table optional	Boolean	If this is `true`, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs. Default value: `false`

Success 200

Field	Type	Description
id	Number	The ID of the SNMP OID.
name	String	The name of the SNMP OID
oid	String	The numeric OID
color	String	A hex color code for the SNMP OID. This will define the color used when graphing this OID. Default value: `#3498db`
unit_of_measurement	String	The unit of measurement for the SNMP OID (e.g. `bytes`, `%`, `Fahrenheit`.)
monitoring_graph_id	Integer	If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.
auto_scale	Boolean	Whether or not results from this OID are automatically scaled by thousands.
display_as_table	Boolean	If this is `true`, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "oid": "1.2.3.4",
    "name": "Test",
    "color": "#3498db",
    "unit_of_measurement": null,
    "monitoring_graph_id": null,
    "auto_scale": false,
    "display_as_table": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Update monitoring graph

Update an existing monitoring graph.

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs/:id

Parameter

Field	Type	Description
monitoring_template_id	Integer	The ID of the monitoring template
id	Integer	The ID of the monitoring graph
name optional	String	A name for the monitoring graph
type optional	String	The type of graph Allowed values: `"line"`, `"bar"`, `"area"`
stacked optional	Boolean	Whether or not values should be stacked on the graph, or drawn independently Default value: `false`

Success 200

Field	Type	Description
id	Integer	The ID of the monitoring graph.
name	String	The name of the monitoring graph
type	String	The type of graph
stacked	Boolean	Whether or not values should be stacked on the graph, or drawn independently

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Aggregate Graph",
    "type": "line",
    "stacked": false
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Update monitoring template

Update an existing monitoring template.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:id

Parameter

Field	Type	Description
id	Integer	The ID of the monitoring template
name optional	String	A name for the monitoring template
snmp_version optional	Integer	Default SNMP queries made using this template to this SNMP version. `2` is version 2c. Allowed values: `1`, `2`, `3`
snmp_community optional	String	Default SNMP queries made using this template to use this SNMP community. If your `snmp_version` is `3`, then this will be used as the SNMPv3 securityName.
snmp3_sec_level optional	String	If you are using SNMPv3, this is the default security level Allowed values: `"noAuthNoPriv"`, `"authNoPriv"`, `"authPriv"`
snmp3_auth_protocol optional	String	If you are using SNMPv3, this is the default authentication protocol Allowed values: `"MD5"`, `"SHA"`
snmp3_auth_passphrase optional	String	If you are using SNMPv3, this is the default authentication pass phrase
snmp3_priv_protocol optional	String	If you are using SNMPv3, this is the default privacy protocol Allowed values: `"DES"`, `"AES"`
snmp3_priv_passphrase optional	String	If you are using SNMPv3, this is the default privacy passphrase
snmp3_context_name optional	String	If you are using SNMPv3, this is the default context name
snmp3_context_engine_id optional	String	If you are using SNMPv3, this is the default context EngineID
icmp optional	Boolean	Whether or not to perform ICMP monitoring Default value: `false`
icmp_latency_threshold optional	Integer	If this is set, then a median latency above this value will put a device into warning status
icmp_loss_threshold optional	Integer	If this is set, then a packet loss percentage above this value will put the device into warning status
collect_interface_statistics optional	Boolean	Whether or not to collect interface statistics Default value: `false`
inventory_model_ids optional	Array	An array of inventory model IDs that should have this monitoring template applied to them.

Success 200

Field	Type	Description
id	Number	The ID of the monitoring template.
name	String	The name of the monitoring template
inventory_model_ids	Array	An array of inventory model IDs that have this monitoring template applied to them.
snmp_version	Integer	Default SNMP queries made using this template to this SNMP version. `2` is version 2c. Allowed values: `1`, `2`, `3`
snmp_community	String	Default SNMP queries made using this template to use this SNMP community. If your `snmp_version` is `3`, then this will be used as the SNMPv3 securityName.
snmp3_sec_level	String	If you are using SNMPv3, this is the default security level Allowed values: `"noAuthNoPriv"`, `"authNoPriv"`, `"authPriv"`
snmp3_auth_protocol	String	If you are using SNMPv3, this is the default authentication protocol Allowed values: `"MD5"`, `"SHA"`
snmp3_auth_passphrase	String	If you are using SNMPv3, this is the default authentication pass phrase
snmp3_priv_protocol	String	If you are using SNMPv3, this is the default privacy protocol Allowed values: `"DES"`, `"AES"`
snmp3_priv_passphrase	String	If you are using SNMPv3, this is the default privacy passphrase
snmp3_context_name	String	If you are using SNMPv3, this is the default context name
snmp3_context_engine_id	String	If you are using SNMPv3, this is the default context EngineID
icmp	Boolean	Whether or not to perform ICMP monitoring
collect_interface_statistics	Boolean	Whether or not to collect interface statistics Default value: `false`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "MikroTik Probe",
    "snmp_version": 2,
    "snmp_community": "somerandomcommunity",
    "snmp3_sec_level": null,
    "snmp3_auth_protocol": null,
    "snmp3_auth_passphrase": null,
    "snmp3_priv_protocol": null,
    "snmp3_priv_passphrase": null,
    "snmp3_context_name": null,
    "snmp3_context_engine_id": null,
    "icmp": true,
    "icmp_latency_threshold": null,
    "icmp_loss_threshold": null,
    "collect_interface_statistics": false,
    "inventory_model_ids": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Network Site IP Addresses

Network_Site_IP_Addresses - Assign an IP to a network site

This endpoint allows you to assign IPv4/IPv6 assignments to a network site or an inventory model field on an network site. Please see the documentation for more details about the different scenarios in which you would pick each entity.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments

Parameter

Field	Type	Description
id	Number	The ID of the network site
subnet	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within an infrastructure/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32.
assigned_entity	String	The entity to assign this to - the network site directly or an inventory item on the network site. Allowed values: `"network_sites"`, `"inventory_items"`
assigned_id optional	Number	The ID of the entity referenced in assigned_entity. If assigned_entity is 'network_sites'
inventory_item_field_id optional	Number	If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.) This is required if assigned_entity is "inventory_items"
description optional	String	An optional description for the assignment

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
network_site_id	Number	The ID of the network site the IP is assigned to
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 53,
     "subnet_id": 4,
     "subnet": "192.168.0.153",
     "assigned_entity": "network_sites",
     "assigned_id": 1,
     "inventory_item_field_id": null,
     "ip_pool_id": 3,
     "network_site_id": 1,
     "description": "Loopback for Router ABC",
     "soft": false
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Network_Site_IP_Addresses - Assign an IP to a network site

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments

Parameter

Field	Type	Description
id	Number	The ID of the network site
subnet	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within an infrastructure/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32.
assigned_entity	String	The entity to assign this to - the network site directly or an inventory item on the network site. Allowed values: `"network_sites"`, `"inventory_items"`
assigned_id optional	Number	The ID of the entity referenced in assigned_entity. If assigned_entity is 'network_sites'
inventory_item_field_id optional	Number	If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.) This is required if assigned_entity is "inventory_items"
description optional	String	An optional description for the assignment

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
network_site_id	Number	The ID of the network site the IP is assigned to
description	String	An optional description for the assignment

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 53,
     "subnet_id": 4,
     "subnet": "192.168.0.153",
     "assigned_entity": "network_sites",
     "assigned_id": 1,
     "ip_pool_id": 3,
     "network_site_id": 1,
     "description": "Loopback for Router ABC"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Network_Site_IP_Addresses - Delete IP assignment

Delete an IP assignment.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the network site
ip_assignment_id	Number	The ID of the IP assignment

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the IP assignment could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "That IP assignment is not assigned to that network site."
         },
         "status_code": 422
     }
 }

Network_Site_IP_Addresses - Get all IP assignments

Retrieve a list of existing IP assignments on the account.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the network site

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
network_site_id	Number	The ID of the network site the IP is assigned to
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 52,
      "subnet_id": 4,
      "subnet": "192.168.0.2",
      "assigned_entity": "network_sites",
      "assigned_id": 1,
      "inventory_item_field_id": null,
      "ip_pool_id": null,
      "network_site_id": 1,
      "description": null,
      "soft": false
    },
    {
      "id": 53,
      "subnet_id": 4,
      "subnet": "192.168.0.153",
      "assigned_entity": "network_sites",
      "assigned_id": 1,
      "inventory_item_field_id": null,
      "ip_pool_id": 3,
      "network_site_id": 1,
      "description": null,
      "soft": false
    },
    {
      "id": 54,
      "subnet_id": 4,
      "subnet": "192.168.0.154",
      "assigned_entity": "inventory_items",
      "assigned_id": 3,
      "inventory_item_field_id": null,
      "ip_pool_id": 3,
      "network_site_id": 1,
      "description": "Some description",
      "soft": false
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Site_IP_Addresses - Get all IP assignments

Retrieve a list of existing IP assignments on the account.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the network site

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
network_site_id	Number	The ID of the network site the IP is assigned to
description	String	An optional description for the assignment

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 52,
      "subnet_id": 4,
      "subnet": "192.168.0.2",
      "assigned_entity": "network_sites",
      "assigned_id": 1,
      "ip_pool_id": null,
      "network_site_id": 1,
      "description": null
    },
    {
      "id": 53,
      "subnet_id": 4,
      "subnet": "192.168.0.153",
      "assigned_entity": "network_sites",
      "assigned_id": 1,
      "ip_pool_id": 3,
      "network_site_id": 1,
      "description": null
    },
    {
      "id": 54,
      "subnet_id": 4,
      "subnet": "192.168.0.154",
      "assigned_entity": "inventory_items",
      "assigned_id": 3,
      "ip_pool_id": 3,
      "network_site_id": 1,
      "description": "Some description"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Site_IP_Addresses - Get individual IP assignment

Retrieve a specific IP assignment.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the network site
ip_assignment_id	Number	The ID of the IP assignment.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
network_site_id	Number	The ID of the network site the IP is assigned to
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 52,
    "subnet_id": 4,
    "subnet": "192.168.0.2",
    "assigned_entity": "network_sites",
    "assigned_id": 1,
    "inventory_item_field_id": null,
    "ip_pool_id": null,
    "network_site_id": 1,
    "description": "Finn & Jake's favorite IP",
    "soft": false
  }
}

Network_Site_IP_Addresses - Get individual IP assignment

Retrieve a specific IP assignment.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the network site
ip_assignment_id	Number	The ID of the IP assignment.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
network_site_id	Number	The ID of the network site the IP is assigned to
description	String	An optional description for the assignment

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 52,
    "subnet_id": 4,
    "subnet": "192.168.0.2",
    "assigned_entity": "network_sites",
    "assigned_id": 1,
    "ip_pool_id": null,
    "network_site_id": 1,
    "description": "Finn & Jake's favorite IP"
  }
}

Network_Site_IP_Addresses - Update IP assignment

Update an existing IP assignment. If the assignment is on an network site, only the subnet can be changed. If it is on an inventory item, the assigned_id, the subnet and inventory_item_field_id can be changed. To change the entity on an assignment other than an inventory item, delete the existing assignment and create a new one.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the network site
ip_assignment_id	Number	The ID of the IP assignment
subnet optional	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a infrastructure/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.
assigned_id optional	Number	Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If you supply this, you must also supply inventory_item_field_id or the query will be rejected. If the inventory item is not assigned to the same network site as the existing assignment, it will also be rejected.
inventory_item_field_id optional	Number	If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).
description optional	String	An optional description for the assignment
make_permanent	Boolean	If this is set to `true`, and the `soft` property of this IP assignment is currently `true`, then this will be changed to a permanent assignment.

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
inventory_item_field_id	Number	If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be `null`.
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
network_site_id	Number	The ID of the network site the IP is assigned to
description	String	An optional description for the assignment
soft	Boolean	If this is `true`, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 52,
    "subnet_id": 4,
    "subnet": "192.168.0.156/32",
    "assigned_entity": "network_sites",
    "assigned_id": 1,
    "inventory_item_field_id": null,
    "ip_pool_id": 3,
    "network_site_id": 1,
    "description": null,
    "soft": false
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Network_Site_IP_Addresses - Update IP assignment

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field	Type	Description
id	Number	The ID of the network site
ip_assignment_id	Number	The ID of the IP assignment
subnet optional	String	The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a infrastructure/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.
assigned_id optional	Number	Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If you supply this, you must also supply inventory_item_field_id or the query will be rejected. If the inventory item is not assigned to the same network site as the existing assignment, it will also be rejected.
inventory_item_field_id optional	Number	If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).
description optional	String	An optional description for the assignment

Success 200

Field	Type	Description
id	Number	The ID of the ip assignment
subnet_id	Number	The ID of the subnet
subnet	String	The IPv4/IPv6 subnet
assigned_entity	String	The type of entity this is assigned to
assigned_id	Number	The ID of the entity this is assigned to
ip_pool_id	Number	If this falls into an IP pool, the ID of the pool, otherwise, null
network_site_id	Number	The ID of the network site the IP is assigned to
description	String	An optional description for the assignment

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 52,
    "subnet_id": 4,
    "subnet": "192.168.0.156/32",
    "assigned_entity": "network_sites",
    "assigned_id": 1,
    "ip_pool_id": 3,
    "network_site_id": 1,
    "description": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Network Site Inventory

Network_Site_Inventory - Get all inventory items

Get a list of inventory at a specific network site.

https://example.sonar.software/api/v1/network/network_sites/:id/inventory_items

Parameter

Field	Type	Description
id	Number	The ID of the network site
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "inventory_model_id": 1,
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:00:00:00:00:0C"
        }
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Site_Inventory - Get individual inventory item

Get a specific inventory item at a specific network site.

https://example.sonar.software/api/v1/network/network_sites/:id/inventory_items/:item_id

Parameter

Field	Type	Description
id	Number	The ID of the network site
item_id	Number	The ID of the inventory item

Success 200

Field	Type	Description
id	Number	The ID of the inventory item
inventory_model_id	Number	The ID of the model
status	String	The status of the device, when inserting this will typically always be 'functional' Allowed values: `"functional"`, `"failed"`, `"lost"`
condition	String	The condition of the device
consumed	Boolean	Whether or not this item has been consumed. If this is not a consumable item, this will always be false.
consumed_at	String	If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.
fields	Array	An array of fields for this item. The structure is detailed below
field_id	Number	The ID of the model field (must be an existing field associated with the inventory_model_id)
data	String	The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "inventory_model_id": 1,
    "status": "functional",
    "purchase_price": 0,
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "00:00:00:00:00:0C"
      }
    ]
  }
}

Network Sites

Network_Sites - Create network site address

Create a new network site address

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses

Parameter

Field	Type	Description
network_site_id	Number	The ID of the network site to add the address to
line1	String	The first line of the address
line2 optional	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
county	String	The county, only returned for US states
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 3,
        "line1": "555 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Network_Sites - Create network site

Create a new network site.

https://example.sonar.software/api/v1/network/network_sites

Parameter

Field	Type	Description
name	String	A unique name for the network site
line1 optional	String	Line1 of the physical address of the site
line2 optional	String	Line2 of the physical address of the site
city optional	String	The city of the site
state optional	String	The state/province of the site
zip optional	String	The zip/postal code of the site
country	String	The country of the site, as a two digit string
latitude	String	The latitude of the site in decimal
longitude	String	The longitude of the site in decimal
height_in_meters	Number	The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

Success 200

Field	Type	Description
id	Number	The ID of the network site
name	String	A descriptive name of the network site
height_in_meters	Number	The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
      "id": 1,
      "name": "My House",
      "height_in_meters": 15
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Network_Sites - Create network site

Create a new network site.

https://example.sonar.software/api/v1/network/network_sites

Parameter

Field	Type	Description
name	String	A unique name for the network site
line1 optional	String	Line1 of the physical address of the site
line2 optional	String	Line2 of the physical address of the site
city optional	String	The city of the site
state optional	String	The state/province of the site
zip optional	String	The zip/postal code of the site
country	String	The country of the site, as a two digit string
latitude	String	The latitude of the site in decimal
longitude	String	The longitude of the site in decimal

Success 200

Field	Type	Description
id	Number	The ID of the network site
name	String	A descriptive name of the network site

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
      "id": 1,
      "name": "My House"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Network_Sites - Delete network site address

Delete a network site address.

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses/:address_id

Parameter

Field	Type	Description
network_site_id	Number	The ID of the network site
address_id	Number	The ID of the address

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "Address deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the address could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Network_Sites - Delete network site

Delete a network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field	Type	Description
id	Number	The ID of the network site

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the network site could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Network site not found.",
         "status_code": 404
     }
 }

Network_Sites - Delete network site

Delete a network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field	Type	Description
id	Number	The ID of the network site

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the network site could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Network site not found.",
         "status_code": 404
     }
 }

Network_Sites - Get all network site addresses

Get a list of the addresses for network site ID :network_site_id

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses

Parameter

Field	Type	Description
network_site_id	Number	The ID of the network site
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states.

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "line1": "12345 Some Ln",
            "line2": "",
            "city": "West Allis",
            "state": "Wisconsin",
            "county": "Milwaukee Co.",
            "zip": "53226",
            "country": "US",
            "latitude": null,
            "longitude": null,
            "address_type_id": 1
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Network_Sites - Get all network sites

Get a list of network sites.

https://example.sonar.software/api/v1/network/network_sites

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the network site
name	String	A descriptive name of the network site
height_in_meters	Number	The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My House",
      "height_in_meters": 100.4
    },
    {
      "id": 2,
      "name": "Jimbob's House of Data",
      "height_in_meters": 50
    },
    {
      "id": 3,
      "name": "Equinix",
      "height_in_meters": 501
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Sites - Get all network sites

Get a list of network sites.

https://example.sonar.software/api/v1/network/network_sites

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the network site
name	String	A descriptive name of the network site

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My House"
    },
    {
      "id": 2,
      "name": "Jimbob's House of Data"
    },
    {
      "id": 3,
      "name": "Equinix"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Sites - Get individual network site address

Get an individual network site address.

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses/:address_id

Parameter

Field	Type	Description
network_site_id	Number	The ID of the network site
address_id	Number	The ID of the address
county	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states.

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 200 OK
{
    "data":
    {
       "line1": "12345 Some Ln",
       "line2": "",
       "city": "West Allis",
       "state": "Wisconsin",
       "county": "Milwaukee Co.",
       "zip": "53226",
       "country": "US",
       "latitude": null,
       "longitude": null,
       "address_type_id": 1
    }
}

Network_Sites - Get individual network site

Get an individual network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field	Type	Description
id	Number	The ID of the account type

Success 200

Field	Type	Description
id	Number	The ID of the network site
name	String	A descriptive name of the network site
height_in_meters	Number	The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
      "id": 1,
      "name": "My House",
      "height_in_meters": 43
    }
}

Network_Sites - Get individual network site

Get an individual network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field	Type	Description
id	Number	The ID of the account type

Success 200

Field	Type	Description
id	Number	The ID of the network site
name	String	A descriptive name of the network site

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
      "id": 1,
      "name": "My House"
    }
}

Network_Sites - Update network site address

Update a network site address.

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses/:address_id

Parameter

Field	Type	Description
network_site_id	Number	The ID of the network site to update the address on
address_id	Number	The ID of the address
line1 optional	String	The first line of the address
line2 optional	String	The second line of the address, typically used for a suite number, apartment number, etc
city optional	String	The city
state optional	String	The state, province or other country subdivision
county optional	String	A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be `null` for any other country.
zip optional	String	The ZIP/postal code
country optional	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude optional	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude optional	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id optional	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field	Type	Description
id	Number	The internal ID of the address
line1	String	The first line of the address
line2	String	The second line of the address, typically used for a suite number, apartment number, etc
city	String	The city
state	String	The state, province or other country subdivision
county	String	The county, only returned for US states
zip	String	The ZIP/postal code
country	String	A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.
latitude	Float	The latitude of the address, in decimal. If no latitude is set, this will be null.
longitude	Float	The longitude of the address, in decimal. If no longitude is set, this will be null.
address_type_id	Number	The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "line1": "444 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Network_Sites - Update network site

Update a network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field	Type	Description
id	Number	The ID of the network site
name	String	A unique name for the network site
height_in_meters	Number	The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

Success 200

Field	Type	Description
id	Number	The ID of the network site
name	String	A descriptive name of the network site
height_in_meters	Number	The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
      "id": 1,
      "name": "My Data Center",
      "height_in_meters": 12
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Network_Sites - Update network site

Update a network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field	Type	Description
id	Number	The ID of the network site
name	String	A unique name for the network site

Success 200

Field	Type	Description
id	Number	The ID of the network site
name	String	A descriptive name of the network site

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
      "id": 1,
      "name": "My Data Center"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Notes

Notes - Create note

Create a new note

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id

Parameter

Field	Type	Description
entity_type	String	The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.
entity_id	Integer	The ID of the entity
category	String	A non-localized string representing the category of the note Allowed values: `"inquiry"`, `"billing"`, `"support"`, `"sales"`, `"other"`
message	String	The content of the note. This may contain HTML
priority optional	Integer	The priority of the note. `0` means a regular note. `1` is a sticky note. `2` is an alert note. Default value: `0` Allowed values: `0`, `1`, `2`

Success 200

Field	Type	Description
id	Integer	An ID representing the individual note
category	String	A non-localized string representing the category of the note
message	String	The content of the note. This may contain HTML
username	String	The username of the user who created the note
priority optional	Integer	The priority of the note. `0` means a regular note. `1` is a sticky note. `2` is an alert note. Default value: `0` Allowed values: `0`, `1`, `2`

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "category": "billing",
    "message": "I just found out I can type ANYTHING I want in here!",
    "username": "ermintrude",
    "priority": 0
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That is not a valid entity type for a note."
         },
         "status_code": 422
     }
 }

Notes - Create note

Create a new note

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id

Parameter

Field	Type	Description
entity_type	String	The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.
entity_id	Number	The ID of the entity
category	String	A non-localized string representing the category of the note Allowed values: `"inquiry"`, `"billing"`, `"support"`, `"sales"`, `"other"`
message	String	The content of the note. This may contain HTML

Success 200

Field	Type	Description
id	Number	An ID representing the individual note
category	String	A non-localized string representing the category of the note
message	String	The content of the note. This may contain HTML
username	String	The username of the user who created the note

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "category": "billing",
    "message": "I just found out I can type ANYTHING I want in here!",
    "username": "ermintrude"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That is not a valid entity type for a note."
         },
         "status_code": 422
     }
 }

Notes - Delete a note

Delete a note.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id/:note_id

Parameter

Field	Type	Description
entity_type	String	The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.
entity_id	Integer	The ID of the entity
note_id	Integer	The ID of the note

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the alerting rotation day/time could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "alerting rotation day/time does not exist.",
         "status_code": 404
     }
 }

Notes - Get all notes for an entity

Get a list of the notes for an entity, such as an account.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id

Parameter

Field	Type	Description
entity_type	String	The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.
entity_id	Integer	The ID of the entity
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return
priority optional	Integer	The priority of the note. `0` means a regular note. `1` is a sticky note. `2` is an alert note. Default value: `0` Allowed values: `0`, `1`, `2`

Success 200

Field	Type	Description
id	Integer	An ID representing the individual note
category	String	A non-localized string representing the category of the note
message	String	The content of the note. This may contain HTML
username	String	The username of the user who created the note
priority optional	Integer	The priority of the note. `0` means a regular note. `1` is a sticky note. `2` is an alert note. Default value: `0` Allowed values: `0`, `1`, `2`

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "category": "billing",
      "message": "Took a call from Adelaide, she said it was time we got paid. She busted out her VISA because she said the invoice pleased her.",
      "username": "reginald",
      "priority": 0
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Notes - Get all notes for an entity

Get a list of the notes for an entity, such as an account.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id

Parameter

Field	Type	Description
entity_type	String	The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.
entity_id	Number	The ID of the entity
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	An ID representing the individual note
category	String	A non-localized string representing the category of the note
message	String	The content of the note. This may contain HTML
username	String	The username of the user who created the note

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "category": "billing",
      "message": "Took a call from Adelaide, she said it was time we got paid. She busted out her VISA because she said the invoice pleased her.",
      "username": "reginald"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Notes - Get individual note for an entity

Get a list of the notes for an entity, such as an account.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id/:note_id

Parameter

Field	Type	Description
entity_type	String	The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.
entity_id	Integer	The ID of the entity
note_id	Integer	The ID of the note

Success 200

Field	Type	Description
id	Integer	An ID representing the individual note
category	String	A non-localized string representing the category of the note
message	String	The content of the note. This may contain HTML
username	String	The username of the user who created the note
priority optional	Integer	The priority of the note. `0` means a regular note. `1` is a sticky note. `2` is an alert note. Default value: `0` Allowed values: `0`, `1`, `2`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "category": "billing",
    "message": "I just found out I can type ANYTHING I want in here!",
    "username": "ermintrude",
    "priority": 1
  }
}

Notes - Get individual note for an entity

Get a list of the notes for an entity, such as an account.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id/:note_id

Parameter

Field	Type	Description
entity_type	String	The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.
entity_id	Number	The ID of the entity
note_id	Number	The ID of the note

Success 200

Field	Type	Description
id	Number	An ID representing the individual note
category	String	A non-localized string representing the category of the note
message	String	The content of the note. This may contain HTML
username	String	The username of the user who created the note

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "category": "billing",
    "message": "I just found out I can type ANYTHING I want in here!",
    "username": "ermintrude"
  }
}

Notes - Update a note

Update a note.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id/:note_id

Parameter

Field	Type	Description
entity_type	String	The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.
entity_id	Integer	The ID of the entity
note_id	Integer	The ID of the note
category	String	The category of the note Allowed values: `"inquiry"`, `"billing"`, `"support"`, `"sales"`, `"other"`
message	String	The note content
priority optional	Integer	The priority of the note. `0` means a regular note. `1` is a sticky note. `2` is an alert note. Allowed values: `0`, `1`, `2`

Success 200

Field	Type	Description
id	Integer	An ID representing the individual note
category	String	A non-localized string representing the category of the note
message	String	The content of the note. This may contain HTML
username	String	The username of the user who created the note
priority optional	Integer	The priority of the note. `0` means a regular note. `1` is a sticky note. `2` is an alert note. Default value: `0` Allowed values: `0`, `1`, `2`

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 4,
    "category": "inquiry",
    "message": "test",
    "username": "admin",
    "priority": 0
  }
}

Packages

Packages - Create package

Create a new package

https://example.sonar.software/api/v1/system/packages

Parameter

Field	Type	Description
name	String	A descriptive name of the package
active	Boolean	Whether or not this package can still be added to accounts
services	Array	An array of service IDs that make up this package

Success 200

Field	Type	Description
id	Number	The internal ID of the package
name	String	A descriptive name of the package
active	Boolean	Whether or not this package can still be added to accounts
services	Array	An array of service IDs that make up this package

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "My Awesome Package",
    "services": [
      1,
      5,
      7
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That service ID is not a valid service"
         },
         "status_code": 422
     }
 }

Packages - Delete package

Delete a package. This will not remove the services from accounts, it will just prevent the package being used in the future. Since packages have an 'active' flag, it generally makes more sense to set them inactive rather than deleting unless you want to permanently remove it from the interface.

https://example.sonar.software/api/v1/system/packages/:id

Parameter

Field	Type	Description
id	Number	The ID of the package

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "Package deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the package could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Package not found",
         "status_code": 404
     }
 }

Packages - Get all packages

Get a list of the service packages in the system

https://example.sonar.software/api/v1/system/packages

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the package
name	String	A descriptive name of the package
active	Boolean	Whether or not this package can still be added to accounts
services	Array	An array of service IDs that make up this package

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "active": true,
      "name": "My Awesome Package",
      "services": [
        1,
        5,
        7
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Packages - Get individual package

Get an individual service package.

https://example.sonar.software/api/v1/system/packages/:id

Parameter

Field	Type	Description
id	Number	The ID of the package

Success 200

Field	Type	Description
id	Number	The internal ID of the package
name	String	A descriptive name of the package
active	Boolean	Whether or not this package can still be added to accounts
services	Array	An array of service IDs that make up this package

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "My Awesome Package",
    "services": [
      1,
      5,
      7
    ]
  }
}

Packages - Update package

Update a service package.

https://example.sonar.software/api/v1/system/packages/:id

Parameter

Field	Type	Description
id	Number	The ID of the package
name	String	A descriptive name of the package
active	Boolean	Whether or not this package can still be added to accounts
services	Array	An array of service IDs that make up this package

Success 200

Field	Type	Description
id	Number	The internal ID of the package
name	String	A descriptive name of the package
active	Boolean	Whether or not this package can still be added to accounts
services	Array	An array of service IDs that make up this package

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "My Awesome Package",
    "services": [
      1,
      5,
      7
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That service ID is not a valid service"
         },
         "status_code": 422
     }
 }

Packages - Update package

Update a service package.

https://example.sonar.software/api/v1/system/packages/:id

Parameter

Field	Type	Description
id	Number	The ID of the package
name	String	A descriptive name of the package
active	Boolean	Whether or not this package can still be added to accounts
services	Array	An array of service IDs that make up this package

Success 200

Field	Type	Description
id	Number	The internal ID of the package
name	String	A descriptive name of the package
active	Boolean	Whether or not this package can still be added to accounts
services	Array	An array of service IDs that make up this package

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "My Awesome Package",
    "services": [
      1,
      5,
      7
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That service ID is not a valid service"
         },
         "status_code": 422
     }
 }

RADIUS Accounts

RADIUS_Accounts - Create a new RADIUS account

Create a new RADIUS account. For this to work, there must be an enabled RADIUS server defined in Sonar.

https://example.sonar.software/api/v1/accounts/:id/radius_accounts

Parameter

Field	Type	Description
id	Number	The ID of the account
username	String	The username for the account
password	String	The password for the account
create_on_server optional	Boolean	Whether or not this account should be created on the RADIUS server. This should generally always be set to true unless you are performing an import and you just need to get Sonar to match what currently exists on the server. Default value: `true`
service_id optional	Number	If the account has multiple data services, you can decide which data service to associate this RADIUS account with. This will affect the groups it is in, if you have groups that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned.

Success 200

Field	Type	Description
id	Number	The ID of the RADIUS account
username	String	The RADIUS account username
password	String	The RADIUS account password
service_id	Number	The ID of the data service this account is associated with

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
       "id": 2,
       "username": "s_westlake",
       "password": "goldeneagle",
       "service_id": 2
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
         },
         "status_code": 422
     }
 }

RADIUS_Accounts - Delete RADIUS account

Delete a RADIUS account.

https://example.sonar.software/api/v1/accounts/:account_id/radius_accounts/:radius_account_id

Parameter

Field Type Description

account_id

Number

The ID of the account

radius_account_id

Number

The ID of the RADIUS account

delete_from_server optional

Boolean

Whether or not to delete the account from the remote RADIUS server, or just from Sonar. You should only set this to false if you don't want to manipulate the remote RADIUS server for some reason.

Default value: true

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the RADIUS account could not be deleted
status_code	Number	422

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "RADIUS account does not exist."
         },
         "status_code": 422
     }
 }

RADIUS_Accounts - Get all RADIUS accounts

Get a list of RADIUS accounts.

https://example.sonar.software/api/v1/accounts/:id/radius_accounts

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the account

Success 200

Field	Type	Description
id	Number	The ID of the RADIUS account
username	String	The RADIUS account username
password	String	The RADIUS account password

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 1,
           "username": "p_luckey",
           "password": "oculus"
       },
       {
           "id": 2,
           "username": "s_westlake",
           "password": "eaglerare"
       }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

RADIUS_Accounts - Get individual RADIUS account

Get an individual RADIUS account.

https://example.sonar.software/api/v1/accounts/:account_id/radius_accounts/:radius_account_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
radius_account_id	Number	The ID of the RADIUS account

Success 200

Field	Type	Description
id	Number	The ID of the RADIUS account
username	String	The RADIUS account username
password	String	The RADIUS account password
service_id	Number	The ID of the data service this account is associated with

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 2,
       "username": "s_westlake",
       "password": "goldeneagle",
       "service_id": 2
   }
}

RADIUS_Accounts - Update RADIUS account

Update a RADIUS account.

https://example.sonar.software/api/v1/accounts/:account_id/radius_accounts/:radius_account_id

Parameter

Field	Type	Description
account_id	Number	The ID of the account
radius_account_id	Number	The ID of the RADIUS account
username	String	The username for RADIUS account
password	String	The password for the RADIUS account
update_on_server optional	Boolean	Whether or not this account should be updated on the remote RADIUS server, or only in Sonar. The only time you should set this to false is if you are trying to reconcile Sonar with your RADIUS server Default value: `true`
service_id optional	Number	If the account has multiple data services, you can decide which data service to associate this RADIUS account with. This will affect the groups it is in, if you have groups that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned.

Success 200

Field	Type	Description
id	Number	The ID of the RADIUS account
username	String	The RADIUS account username
password	String	The RADIUS account password
service_id	Number	The ID of the data service this account is associated with

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 2,
       "username": "s_westlake",
       "password": "regulareagle",
       "service_id": 2
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken."
         },
         "status_code": 422
     }
 }

RADIUS Groups

RADIUS_Groups - Create a new RADIUS group

Create a new RADIUS group. If there is an enabled RADIUS server in good status in Sonar, this group will immediately be created on it with appropriate accounts associated.

https://example.sonar.software/api/v1/network/provisioning/radius_groups

Parameter

Field	Type	Description
name	String	The name of the RADIUS group
priority	Number	The priority for this RADIUS group
delinquent optional	Number	If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked. Default value: `3`
active optional	Number	If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked. Default value: `3`
fall_through optional	Boolean	Whether fall-through is enabled or not on this RADIUS group. Default value: `false`
account_groups optional	Array	An array of account group IDs that are a relation to this RADIUS group.
account_types optional	Array	An array of account type IDs that are a relation to this RADIUS group.
services optional	Array	An array of data service IDs that are a relation to this RADIUS group.
account_statuses optional	Array	An array of account status IDs that are a relation to this RADIUS group.

Success 200

Field	Type	Description
id	Number	The ID of the RADIUS group
name	String	The name of the RADIUS group
priority	Number	The priority for this RADIUS group
delinquent	Number	If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
fall_through	Boolean	Whether fall-through is enabled or not on this RADIUS group.
account_groups	Array	An array of account group IDs that are a relation to this RADIUS group.
account_types	Array	An array of account type IDs that are a relation to this RADIUS group.
services	Array	An array of data service IDs that are a relation to this RADIUS group.
account_statuses	Array	An array of account status IDs that are a relation to this RADIUS group.

Success-Response:

 HTTP/1.1 201 OK
 {
  "data": {
    "id": 7,
    "name": "My Group Name?",
    "priority": 15,
    "active": 3,
    "delinquent": 2,
    "fall_through": true,
    "account_groups": [],
    "account_types": [
      1
    ],
    "services": [
      2,
      1
    ],
    "account_statuses": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The RADIUS group name has already been taken.",
         },
         "status_code": 422
     }
 }

RADIUS_Groups - Create a new reply attribute

Create a new RADIUS group reply attribute. If there is an enabled RADIUS server in good status in Sonar, this attribute will immediately be created on it with appropriate groups associated.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes

Parameter

Field Type Description

attribute

String

The attribute name

operator

String

The operator for the attribute

Allowed values: "=", ":=", "+="

String

The reply value for the attribute

Success 200

Field	Type	Description
id	Number	The ID of the attribute
attribute	String	The attribute name
operator	String	The operator for the attribute
reply	String	The reply value for the attribute

Success-Response:

 HTTP/1.1 201 OK
 {
  "data": {
    "id": 3,
    "attribute": "Some Other Attribute",
    "operator": "+=",
    "reply": "Some Other Value"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "Attribute test123 is duplicated. You may only include each attribute once.",
         },
         "status_code": 422
     }
 }

RADIUS_Groups - Delete RADIUS group

Delete a RADIUS group. This will immediately remove the group from your RADIUS server, if it is enabled and in a good status.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id

Parameter

Field	Type	Description
id	Number	The ID of the RADIUS group.

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the RADIUS group could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "RADIUS group does not exist."
         },
         "status_code": 404
     }
 }

RADIUS_Groups - Delete reply attribute

Delete a RADIUS group reply attribute.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes/:attribute_id

Parameter

Field	Type	Description
id	Number	The ID of the RADIUS group
attribute_id	Number	The ID of the attribute

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the RADIUS reply attribute could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "RADIUS reply attribute does not exist."
         },
         "status_code": 404
     }
 }

RADIUS_Groups - Get all RADIUS groups

Get a list of RADIUS groups.

https://example.sonar.software/api/v1/network/provisioning/radius_groups

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the RADIUS group
name	String	The name of the RADIUS group
priority	Number	The priority for this RADIUS group
delinquent	Number	If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
fall_through	Boolean	Whether fall-through is enabled or not on this RADIUS group.
account_groups	Array	An array of account group IDs that are a relation to this RADIUS group.
account_types	Array	An array of account type IDs that are a relation to this RADIUS group.
services	Array	An array of data service IDs that are a relation to this RADIUS group.
account_statuses	Array	An array of account status IDs that are a relation to this RADIUS group.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Delinquent",
      "priority": 1,
      "active": 3,
      "delinquent": 1,
      "fall_through": false,
      "account_groups": [],
      "account_types": [
        2,
        1
      ],
      "services": [],
      "account_statuses": []
    },
    {
      "id": 2,
      "name": "Commercial With Platinum Data Service",
      "priority": 2,
      "active": 3,
      "delinquent": 3,
      "fall_through": true,
      "account_groups": [],
      "account_types": [
        2
      ],
      "services": [
        1
      ],
      "account_statuses": []
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

RADIUS_Groups - Get all reply attributes

Get a list of of attributes for a specific group.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes

Parameter

Field	Type	Description
id	Number	The ID of the RADIUS group
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the attribute
attribute	String	The attribute name
operator	String	The operator for the attribute
reply	String	The reply value for the attribute

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "attribute": "Some Other Attribute",
      "operator": "+=",
      "reply": "Some Other Value"
    },
    {
      "id": 2,
      "attribute": "Some Attribute",
      "operator": "=",
      "reply": "Some Value"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

RADIUS_Groups - Get individual RADIUS group

Get an individual RADIUS group.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id

Parameter

Field	Type	Description
id	Number	The ID of the RADIUS group

Success 200

Field	Type	Description
id	Number	The ID of the RADIUS group
name	String	The name of the RADIUS group
priority	Number	The priority for this RADIUS group
delinquent	Number	If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
fall_through	Boolean	Whether fall-through is enabled or not on this RADIUS group.
account_groups	Array	An array of account group IDs that are a relation to this RADIUS group.
account_types	Array	An array of account type IDs that are a relation to this RADIUS group.
services	Array	An array of data service IDs that are a relation to this RADIUS group.
account_statuses	Array	An array of account status IDs that are a relation to this RADIUS group.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "name": "My Group Name?",
    "priority": 15,
    "active": 3,
    "delinquent": 2,
    "fall_through": true,
    "account_groups": [],
    "account_types": [
      1
    ],
    "services": [
      2,
      1
    ],
    "account_statuses": []
  }
}

RADIUS_Groups - Get individual reply attribute

Get an individual RADIUS group.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes/:attribute_id

Parameter

Field	Type	Description
id	Number	The ID of the RADIUS group
attribute_id	Number	The ID of the attribute

Success 200

Field	Type	Description
id	Number	The ID of the attribute
attribute	String	The attribute name
operator	String	The operator for the attribute
reply	String	The reply value for the attribute

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 3,
    "attribute": "Some Other Attribute",
    "operator": "+=",
    "reply": "Some Other Value"
  }
}

RADIUS_Groups - Update RADIUS group

Update a RADIUS group.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id

Parameter

Field	Type	Description
id	Number	The ID of the RADIUS group
name optional	String	The name of the RADIUS group
priority optional	Number	The priority for this RADIUS group
delinquent optional	Number	If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked. Default value: `3`
active optional	Number	If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked. Default value: `3`
fall_through optional	Boolean	Whether fall-through is enabled or not on this RADIUS group. Default value: `false`
account_groups optional	Array	An array of account group IDs that are a relation to this RADIUS group.
account_types optional	Array	An array of account type IDs that are a relation to this RADIUS group.
services optional	Array	An array of data service IDs that are a relation to this RADIUS group.
account_statuses optional	Array	An array of account status IDs that are a relation to this RADIUS group.

Success 200

Field	Type	Description
id	Number	The ID of the RADIUS group
name	String	The name of the RADIUS group
priority	Number	The priority for this RADIUS group
delinquent	Number	If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.
active	Number	If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.
fall_through	Boolean	Whether fall-through is enabled or not on this RADIUS group.
account_groups	Array	An array of account group IDs that are a relation to this RADIUS group.
account_types	Array	An array of account type IDs that are a relation to this RADIUS group.
services	Array	An array of data service IDs that are a relation to this RADIUS group.
account_statuses	Array	An array of account status IDs that are a relation to this RADIUS group.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "name": "My Group Name?",
    "priority": 15,
    "active": 3,
    "delinquent": 2,
    "fall_through": true,
    "account_groups": [],
    "account_types": [
      1
    ],
    "services": [
      2,
      1
    ],
    "account_statuses": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

RADIUS_Groups - Update reply attribute

Update a RADIUS group reply attribute.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes/:attribute_id

Parameter

Field	Type	Description
id	Number	The ID of the RADIUS group
attribute_id	Number	The ID of the attribute
attribute optional	String	The attribute name
operator optional	String	The operator for the attribute Allowed values: `"="`, `":="`, `"+="`
reply optional	String	The reply value for the attribute

Success 200

Field	Type	Description
id	Number	The ID of the attribute
attribute	String	The attribute name
operator	String	The operator for the attribute
reply	String	The reply value for the attribute

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 3,
    "attribute": "Some Other Attribute",
    "operator": "+=",
    "reply": "Some Other Value"
  }
}

Rate Centers

Rate_Centers - Create a new rate center

Create a new rate center. A rate center is used to store DIDs for voice services.

https://example.sonar.software/api/v1/system/voice/rate_centers

Parameter

Field	Type	Description
name	String	A name for the rate center

Success 200

Field	Type	Description
id	Number	The ID of the rate center.
name	String	The name of the rate center

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "My rate center",
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Rate_Centers - Delete a rate center

Delete a rate center

https://example.sonar.software/api/v1/system/voice/rate_centers/:id

Parameter

Field	Type	Description
id	Number	The ID of the rate center

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the rate center could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Rate center does not exist.",
         "status_code": 404
     }
 }

Rate_Centers - Get all rate centers

Get all rate centers

https://example.sonar.software/api/v1/system/voice/rate_centers

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the rate center.
name	String	The name of the rate center

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "My rate center"
    },
    {
      "id": 1,
      "name": "Another rate center"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Rate_Centers - Get an individual rate center

Get an individual rate center

https://example.sonar.software/api/v1/system/voice/rate_centers/:id

Parameter

Field	Type	Description
id	Number	The ID of the rate center

Success 200

Field	Type	Description
id	Number	The ID of the rate center.
name	String	The name of the rate center

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "ABC123"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Rate_Centers - Update rate center

Update an existing rate center.

https://example.sonar.software/api/v1/system/voice/rate_centers/:id

Parameter

Field	Type	Description
id	Number	The rate center ID
name optional	String	The name of the rate center

Success 200

Field	Type	Description
id	Number	The ID of the rate center.
name	String	The name of the rate center

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "My updated name"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Roles

Roles - Get all roles

Get a list of roles from within Sonar.

https://example.sonar.software/api/v1/roles/

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the role
name	String	The name of the role

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 2,
            "name": "Read Only"
        },
        {
            "id": 3,
            "name": "Network Support"
        },
        {
            "id": 1,
            "name": "Super Admin"
        }
    ],
    "paginator": {
        "total_count": 3,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Roles - Get individual role

Get data on an Get individual role.

https://example.sonar.software/api/v1/roles/:id

Example usage:

curl -i https://example.sonar.software/api/v1/roles/1

Parameter

Field	Type	Description
id	Number	The id of the role

Success 200

Field	Type	Description
id	Number	The internal id of the role
name	String	The name of the role

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Super Admin"
    }
}

Scheduled Events

Scheduled_Events - Create a new scheduled event

Create a new scheduled event.

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
event_type	String	The type of scheduled event this is Allowed values: `"add_service"`, `"remove_service"`, `"change_status"`, `"price_override_service"`, `"remove_price_override_from_service"`, `"add_package"`, `"remove_package"`
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC (YYYY-MM-DD HH:mm:ss format, in 24 hour time.)
primary_value	String	The primary value for the event. The primary value corresponds to the event. For `add_service`, it is the service ID to add to the account. For `remove_service`, it is the `unique_service_relationship_id` for the service currently on the account. For `change_status`, it is the ID of the account status to change the account to. For `price_override_service`, it is the `unique_service_relationship_id` for the service on the account that you want to price override. For `remove_price_override_from_service`, it is the `unique_service_relationship_id` for the service you want to remove the price override from.
secondary_value optional	String	The secondary value for the event. This is currently only used for the event `price_override_service`, and it is the amount, as a decimal, that you want to price override the service to.
proration_override optional	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event, and can only be set if you have account superuser permissions. If this is `false`, the system default price override selection will be used. Default value: `false`
prorate optional	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true, and can only be set if you have account superuser permissions. Default value: `false`

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled event.
event_type	String	The type of scheduled event this is
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC
primary_value	String	The primary value for the event
secondary_value	String	The secondary value for the event
proration_override	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.
prorate	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true
completed	Boolean	Whether or not the job has been completed
user_id	Integer	The ID of the user that created this event

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "event_type": "add_service",
    "scheduled_datetime": "2016-10-25 07:00:00",
    "primary_value": "1",
    "secondary_value": null,
    "proration_override": false,
    "prorate": false,
    "completed": false,
    "user_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "scheduled_datetime": "The scheduled datetime cannot be in the past."
     },
     "status_code": 422
   }
 }

Scheduled_Events - Create a new scheduled event

Create a new scheduled event.

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
event_type	String	The type of scheduled event this is Allowed values: `"add_service"`, `"remove_service"`, `"change_status"`, `"price_override_service"`, `"remove_price_override_from_service"`
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC (YYYY-MM-DD HH:mm:ss format, in 24 hour time.)
primary_value	String	The primary value for the event. The primary value corresponds to the event. For `add_service`, it is the service ID to add to the account. For `remove_service`, it is the `unique_service_relationship_id` for the service currently on the account. For `change_status`, it is the ID of the account status to change the account to. For `price_override_service`, it is the `unique_service_relationship_id` for the service on the account that you want to price override. For `remove_price_override_from_service`, it is the `unique_service_relationship_id` for the service you want to remove the price override from.
secondary_value optional	String	The secondary value for the event. This is currently only used for the event `price_override_service`, and it is the amount, as a decimal, that you want to price override the service to.
proration_override optional	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event, and can only be set if you have account superuser permissions. If this is `false`, the system default price override selection will be used. Default value: `false`
prorate optional	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true, and can only be set if you have account superuser permissions. Default value: `false`

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled event.
event_type	String	The type of scheduled event this is
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC
primary_value	String	The primary value for the event
secondary_value	String	The secondary value for the event
proration_override	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.
prorate	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true
completed	Boolean	Whether or not the job has been completed
user_id	Integer	The ID of the user that created this event

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "event_type": "add_service",
    "scheduled_datetime": "2016-10-25 07:00:00",
    "primary_value": "1",
    "secondary_value": null,
    "proration_override": false,
    "prorate": false,
    "completed": false,
    "user_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "scheduled_datetime": "The scheduled datetime cannot be in the past."
     },
     "status_code": 422
   }
 }

Scheduled_Events - Delete a scheduled event

Delete a scheduled event

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
id	Integer	The ID of the scheduled event

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the scheduled event could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "scheduled event does not exist.",
         "status_code": 404
     }
 }

Scheduled_Events - Get all scheduled events

Get all scheduled events

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return
account_id	Integer	The ID of the account to get events for

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled event.
event_type	String	The type of scheduled event this is
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC
primary_value	String	The primary value for the event
secondary_value	String	The secondary value for the event
proration_override	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.
prorate	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true
completed	Boolean	Whether or not the job has been completed
user_id	Integer	The ID of the user that created this event

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "event_type": "add_service",
      "scheduled_datetime": "2016-10-25 07:00:00",
      "primary_value": "1",
      "secondary_value": null,
      "proration_override": false,
      "prorate": false,
      "completed": false,
      "user_id": 1
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Scheduled_Events - Get all scheduled events

Get all scheduled events

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return
account_id	Integer	The ID of the account to get events for

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled event.
event_type	String	The type of scheduled event this is
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC
primary_value	String	The primary value for the event
secondary_value	String	The secondary value for the event
proration_override	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.
prorate	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true
completed	Boolean	Whether or not the job has been completed
user_id	Integer	The ID of the user that created this event

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "event_type": "add_service",
      "scheduled_datetime": "2016-10-25 07:00:00",
      "primary_value": "1",
      "secondary_value": null,
      "proration_override": false,
      "prorate": false,
      "completed": false,
      "user_id": 1
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Scheduled_Events - Get an individual scheduled event

Get an individual scheduled event

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account to get events for
id	Integer	The ID of the scheduled event

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled event.
event_type	String	The type of scheduled event this is
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC
primary_value	String	The primary value for the event
secondary_value	String	The secondary value for the event
proration_override	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.
prorate	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true
completed	Boolean	Whether or not the job has been completed
user_id	Integer	The ID of the user that created this event

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "event_type": "add_service",
    "scheduled_datetime": "2016-10-25 07:00:00",
    "primary_value": "1",
    "secondary_value": null,
    "proration_override": false,
    "prorate": false,
    "completed": false,
    "user_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Scheduled_Events - Get an individual scheduled event

Get an individual scheduled event

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account to get events for
id	Integer	The ID of the scheduled event

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled event.
event_type	String	The type of scheduled event this is
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC
primary_value	String	The primary value for the event
secondary_value	String	The secondary value for the event
proration_override	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.
prorate	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true
completed	Boolean	Whether or not the job has been completed
user_id	Integer	The ID of the user that created this event

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "event_type": "add_service",
    "scheduled_datetime": "2016-10-25 07:00:00",
    "primary_value": "1",
    "secondary_value": null,
    "proration_override": false,
    "prorate": false,
    "completed": false,
    "user_id": 1
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Scheduled_Events - Update scheduled event

Update an existing scheduled event.

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
id	Integer	The ID of the scheduled event
event_type	String	The type of scheduled event this is Allowed values: `"add_service"`, `"remove_service"`, `"change_status"`, `"price_override_service"`, `"remove_price_override_from_service"`, `"add_package"`, `"remove_package"`
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC (YYYY-MM-DD HH:mm:ss format, in 24 hour time.)
primary_value	String	The primary value for the event. The primary value corresponds to the event. For `add_service`, it is the service ID to add to the account. For `remove_service`, it is the `unique_service_relationship_id` for the service currently on the account. For `change_status`, it is the ID of the account status to change the account to. For `price_override_service`, it is the `unique_service_relationship_id` for the service on the account that you want to price override. For `remove_price_override_from_service`, it is the `unique_service_relationship_id` for the service you want to remove the price override from. For `add_package`, it is the package ID. For `remove_package` it is the unique_package_id from the account to service relationship.
secondary_value optional	String	The secondary value for the event. This is currently only used for the event `price_override_service`, and it is the amount, as a decimal, that you want to price override the service to.
proration_override optional	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event, and can only be set if you have account superuser permissions. If this is `false`, the system default price override selection will be used.
prorate optional	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true, and can only be set if you have account superuser permissions.

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled event.
event_type	String	The type of scheduled event this is
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC
primary_value	String	The primary value for the event
secondary_value	String	The secondary value for the event
proration_override	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.
prorate	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true
completed	Boolean	Whether or not the job has been completed
user_id	Integer	The ID of the user that created this event

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Scheduled_Events - Update scheduled event

Update an existing scheduled event.

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field	Type	Description
account_id	Integer	The ID of the account
id	Integer	The ID of the scheduled event
event_type	String	The type of scheduled event this is Allowed values: `"add_service"`, `"remove_service"`, `"change_status"`, `"price_override_service"`, `"remove_price_override_from_service"`
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC (YYYY-MM-DD HH:mm:ss format, in 24 hour time.)
primary_value	String	The primary value for the event. The primary value corresponds to the event. For `add_service`, it is the service ID to add to the account. For `remove_service`, it is the `unique_service_relationship_id` for the service currently on the account. For `change_status`, it is the ID of the account status to change the account to. For `price_override_service`, it is the `unique_service_relationship_id` for the service on the account that you want to price override. For `remove_price_override_from_service`, it is the `unique_service_relationship_id` for the service you want to remove the price override from.
secondary_value optional	String	The secondary value for the event. This is currently only used for the event `price_override_service`, and it is the amount, as a decimal, that you want to price override the service to.
proration_override optional	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event, and can only be set if you have account superuser permissions. If this is `false`, the system default price override selection will be used.
prorate optional	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true, and can only be set if you have account superuser permissions.

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled event.
event_type	String	The type of scheduled event this is
scheduled_datetime	DateTime	The scheduled date and time for this event to occur, in UTC
primary_value	String	The primary value for the event
secondary_value	String	The secondary value for the event
proration_override	Boolean	Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.
prorate	Boolean	Whether or not to prorate this event, if proration is valid. This value is only checked if `proration_override` is true
completed	Boolean	Whether or not the job has been completed
user_id	Integer	The ID of the user that created this event

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules

Schedules - Create a new schedule blocker

Create a new schedule blocker.

https://example.sonar.software/api/v1/scheduling/schedule_blockers

Parameter

Field	Type	Description
name	String	A name for the schedule blocker
sunday	Boolean	`true` if this schedule blocks on Sunday, `false` if not
monday	Boolean	`true` if this schedule blocks on Monday, `false` if not
tuesday	Boolean	`true` if this schedule blocks on Tuesday, `false` if not
wednesday	Boolean	`true` if this schedule blocks on Wednesday, `false` if not
thursday	Boolean	`true` if this schedule blocks on Thursday, `false` if not
friday	Boolean	`true` if this schedule blocks on Friday, `false` if not
saturday	Boolean	`true` if this schedule blocks on Saturday, `false` if not
start_timestamp	Time	The start of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
end_timestamp	Time	The end of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
user_ids	Array	An array of user IDs that this blocker should apply to
start	Date	The start date for this blocker
weeks	Integer	The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.
repetitions	Integer	How many times this blocker repeats. Ignored if `infinite_repetitions` is true
infinite_repetitions	Boolean	If this is `true`, this blocker repeats forever

Success 200

Field	Type	Description
id	Integer	The ID of the blocker
name	String	A name for the schedule blocker
sunday	Boolean	`true` if this schedule blocks on Sunday, `false` if not
monday	Boolean	`true` if this schedule blocks on Monday, `false` if not
tuesday	Boolean	`true` if this schedule blocks on Tuesday, `false` if not
wednesday	Boolean	`true` if this schedule blocks on Wednesday, `false` if not
thursday	Boolean	`true` if this schedule blocks on Thursday, `false` if not
friday	Boolean	`true` if this schedule blocks on Friday, `false` if not
saturday	Boolean	`true` if this schedule blocks on Saturday, `false` if not
start_timestamp	Time	The start of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
end_timestamp	Time	The end of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
user_ids	Array	An array of user IDs that this blocker should apply to
start	Date	The start date for this blocker
weeks	Integer	The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.
repetitions	Integer	How many times this blocker repeats. Ignored if `infinite_repetitions` is true
infinite_repetitions	Boolean	If this is `true`, this blocker repeats forever

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
     "id": 2,
     "name": "brunch",
     "sunday": false,
     "monday": true,
     "tuesday": false,
     "wednesday": false,
     "thursday": false,
     "friday": false,
     "saturday": false,
     "start_timestamp": "13:55",
     "end_timestamp": "14:30",
     "user_ids": [
       1
     ],
     "start": "2017-01-01",
     "weeks": 1,
     "repetitions": 1,
     "infinite_repetitions": true
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "infinite_repetitions": "Infinite repetitions must be a boolean."
     },
     "status_code": 422
   }
 }

Schedules - Create a new schedule day/time

Create a new schedule day/time. A schedule day and time is contained within a schedule, so you must create a schedule first.

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days

Parameter

Field	Type	Description
schedule_id	Number	The ID of the schedule that contains this day/time
day	Number	The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday. Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6`
start_timestamp	Time	The starting time for this particular period, in Hour:Minute format, where minute must be in 15 minute increments. This is in the Sonar timezone, not UTC.
end_timestamp	Time	The ending time for this particular period, in Hour:Minute format, where minute must be in 15 minute increments. This is in the Sonar timezone, not UTC.

Success 200

Field	Type	Description
id	Number	The ID of the schedule day/time.
day	Number	The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.
start_timestamp	Time	The starting time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.
end_timestamp	Time	The ending time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "day": 1,
    "start_timestamp": "13:45:00",
    "end_timestamp": "17:00:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "day": "The day must be between 0 and 6."
     },
     "status_code": 422
   }
 }

Schedules - Create a new schedule

Create a new schedule. A schedule is a container for availability, or lack thereof. You must add days to the schedule for it to have any purpose.

https://example.sonar.software/api/v1/scheduling/schedules

Parameter

Field	Type	Description
name	String	A name for the schedule
user_ids	Array	An array of user IDs that this schedule is applied to
job_type_ids	Array	An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container.
start	Date	The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.
available	Boolean	Whether this schedule defines availability, or lack of availability. A schedule with `available` set to `false` will always override another schedule with `available` set to `true`.
infinite_repetitions	Boolean	Set this to `true` if you want this schedule to run indefinitely
repetitions	Number	How many times this schedule should repeat. 0 to never repeat.
weeks	Number	How often the repetition should occur, in weeks. If this is 1, this schedule repeats every week. If this is 2, the schedule runs for one week, then breaks for one week, then runs for one week, then breaks for one week, etc. If this is 3, the schedule runs for one week, then breaks for two weeks, then runs for one week, then breaks for two weeks, etc. This interacts with `repetitions` by repeating `repetitions` times for the number of active weeks. For example, if weeks is 2, and repetitions is 1, this schedule would run for a week, skip a week, run for a week, and then stop.

Success 200

Field	Type	Description
id	Number	The ID of the schedule.
name	String	The name of the schedule
user_ids	Array	An array of user IDs that this schedule is applied to
job_type_ids	Array	An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container
start	Date	The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.
available	Boolean	Whether this schedule defines availability, or lack of availability.
infinite_repetitions	Boolean	Will be `true` if this schedule runs indefinitely
repetitions	Number	How many times this schedule should repeat.
weeks	Number	How often the repetition should occur, in weeks.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 6,
    "user_ids": [ 1 ],
    "job_type_ids": [ 1 ],
    "name": "Test",
    "start": "2016-08-05",
    "available": true,
    "infinite_repetitions": false,
    "repetitions": 1,
    "weeks": 3
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "That user does not exist."
     },
     "status_code": 422
   }
 }

Schedules - Create a new scheduled time off

Create a new scheduled time off. This is typically used to block out a span of time when an employee is unavailable, for example, during vacation.

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs

Parameter

Field	Type	Description
user_id	Integer	The ID of the user that has time off scheduled
start_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
end_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
name	String	A description/reason for the time off.

Success 200

Field	Type	Description
user_id	Integer	The ID of the user that has time off scheduled
start_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
end_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
name	String	A description/reason for the time off.
id	Number	The ID of the scheduled time off.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 10,
    "user_id": 1,
    "start_time": "2016-11-01 01:00:00",
    "end_time": "2016-11-01 01:30:00"
    "name": "test"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Schedules - Delete a schedule blocker

Delete a schedule blocker

https://example.sonar.software/api/v1/scheduling/schedule_blockers/:id

Parameter

Field	Type	Description
id	Integer	The ID of the schedule blocker

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the schedule blocker could not be deleted
status_code	Integer	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "schedule blocker does not exist.",
         "status_code": 404
     }
 }

Schedules - Delete a schedule day/time

Delete a schedule day/time

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days/:id

Parameter

Field	Type	Description
schedule_id	Number	The ID of the schedule that contains this day/time
id	Number	The ID of the schedule day/time

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the schedule day/time could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "schedule day/time does not exist.",
         "status_code": 404
     }
 }

Schedules - Delete a schedule

Delete a schedule

https://example.sonar.software/api/v1/scheduling/schedules/:id

Parameter

Field	Type	Description
id	Number	The ID of the schedule

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the schedule could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Schedule does not exist.",
         "status_code": 404
     }
 }

Schedules - Delete a scheduled time off

Delete a scheduled time off

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs/:id

Parameter

Field	Type	Description
id	Number	The ID of the scheduled time off

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the scheduled time off could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "scheduled time off does not exist.",
         "status_code": 404
     }
 }

Schedules - Get all schedule blockers

Get all schedule blockers

https://example.sonar.software/api/v1/scheduling/schedule_blockers

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the blocker
name	String	A name for the schedule blocker
sunday	Boolean	`true` if this schedule blocks on Sunday, `false` if not
monday	Boolean	`true` if this schedule blocks on Monday, `false` if not
tuesday	Boolean	`true` if this schedule blocks on Tuesday, `false` if not
wednesday	Boolean	`true` if this schedule blocks on Wednesday, `false` if not
thursday	Boolean	`true` if this schedule blocks on Thursday, `false` if not
friday	Boolean	`true` if this schedule blocks on Friday, `false` if not
saturday	Boolean	`true` if this schedule blocks on Saturday, `false` if not
start_timestamp	Time	The start of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
end_timestamp	Time	The end of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
user_ids	Array	An array of user IDs that this blocker should apply to
start	Date	The start date for this blocker
weeks	Integer	The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.
repetitions	Integer	How many times this blocker repeats. Ignored if `infinite_repetitions` is true
infinite_repetitions	Boolean	If this is `true`, this blocker repeats forever

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Brunch",
      "sunday": false,
      "monday": true,
      "tuesday": false,
      "wednesday": false,
      "thursday": false,
      "friday": false,
      "saturday": false,
      "start_timestamp": "13:55",
      "end_timestamp": "14:30",
      "user_ids": [
        1
      ],
      "start": "2017-01-01",
      "weeks": 1,
      "repetitions": 1,
      "infinite_repetitions": true
    },
    {
      "id": 7,
      "name": "Lunch",
      "sunday": false,
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": false,
      "friday": false,
      "saturday": false,
      "start_timestamp": "00:00",
      "end_timestamp": "00:45",
      "user_ids": [
        1
      ],
      "start": "2017-02-02",
      "weeks": 1,
      "repetitions": 1,
      "infinite_repetitions": true
    },
    {
      "id": 8,
      "name": "Dinner",
      "sunday": false,
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": false,
      "friday": false,
      "saturday": false,
      "start_timestamp": "00:00",
      "end_timestamp": "00:30",
      "user_ids": [
        1
      ],
      "start": "2017-02-01",
      "weeks": 1,
      "repetitions": 1,
      "infinite_repetitions": true
    },
    {
      "id": 9,
      "name": "Breakfast",
      "sunday": true,
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": true,
      "friday": true,
      "saturday": true,
      "start_timestamp": "00:30",
      "end_timestamp": "11:00",
      "user_ids": [],
      "start": "2017-02-01",
      "weeks": 1,
      "repetitions": 1,
      "infinite_repetitions": true
    }
  ],
  "paginator": {
    "total_count": 4,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Schedules - Get all scheduled time offs

Get all scheduled time offs

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs

Parameter

Field	Type	Description
limit optional	Integer	The number of entries to return
page optional	Integer	The page of results to return

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled time off.
user_id	Integer	The ID of the user that has time off scheduled
start_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
end_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
name	String	A description/reason for the time off.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "user_id": 9,
      "start_time": "2016-10-18 21:00:00",
      "end_time": "2016-10-18 22:00:00",
      "name": "Matt's Vacation"
    },
    {
      "id": 3,
      "user_id": 9,
      "start_time": "2016-10-18 01:00:00",
      "end_time": "2016-10-20 19:45:00",
      "name": "Really long dentist appointment"
    },
    {
      "id": 6,
      "user_id": 1,
      "start_time": "2016-10-19 00:00:00",
      "end_time": "2016-10-19 23:45:00",
      "name": "Just a block of time off for user ID 1"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Schedules - Get all schedules

Get all schedules

https://example.sonar.software/api/v1/scheduling/schedules

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the schedule.
name	String	The name of the schedule
user_ids	Array	An array of user IDs that this schedule is applied to
job_type_ids	Array	An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container
start	Date	The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.
available	Boolean	Whether this schedule defines availability, or lack of availability.
infinite_repetitions	Boolean	Will be `true` if this schedule runs indefinitely
repetitions	Number	How many times this schedule should repeat.
weeks	Number	How often the repetition should occur, in weeks.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "user_ids": [ 1 ],
      "job_type_ids": [ 1 ],
      "name": "Commercial Installs",
      "start": "2016-08-05",
      "available": true,
      "infinite_repetitions": false,
      "repetitions": 90,
      "weeks": 1
    },
    {
      "id": 4,
      "user_ids": [ 2, 3 ],
      "name": "Residential Installs",
      "start": "2016-08-05",
      "available": true,
      "infinite_repetitions": true,
      "repetitions": 1,
      "weeks": 3
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Schedules - Get all schedule day/times

Get all schedule day/times

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days

Parameter

Field	Type	Description
schedule_id	Number	The ID of the schedule
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the schedule day/time.
day	Number	The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.
start_timestamp	Time	The starting time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.
end_timestamp	Time	The ending time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "day": 1,
      "start_timestamp": "08:00",
      "end_timestamp": "12:00"
    },
    {
      "id": 6,
      "day": 1,
      "start_timestamp": "20:00",
      "end_timestamp": "22:00"
    },
    {
      "id": 7,
      "day": 1,
      "start_timestamp": "00:00",
      "end_timestamp": "08:00"
    },
    {
      "id": 8,
      "day": 1,
      "start_timestamp": "10:00",
      "end_timestamp": "12:00"
    },
    {
      "id": 9,
      "day": 1,
      "start_timestamp": "00:00",
      "end_timestamp": "23:00"
    }
  ],
  "paginator": {
    "total_count": 5,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Schedules - Get an individual schedule blocker

Get an individual schedule blocker

https://example.sonar.software/api/v1/scheduling/schedule_blockers/:id

Parameter

Field	Type	Description
id	Integer	The ID of the schedule blocker

Success 200

Field	Type	Description
id	Integer	The ID of the blocker
name	String	A name for the schedule blocker
sunday	Boolean	`true` if this schedule blocks on Sunday, `false` if not
monday	Boolean	`true` if this schedule blocks on Monday, `false` if not
tuesday	Boolean	`true` if this schedule blocks on Tuesday, `false` if not
wednesday	Boolean	`true` if this schedule blocks on Wednesday, `false` if not
thursday	Boolean	`true` if this schedule blocks on Thursday, `false` if not
friday	Boolean	`true` if this schedule blocks on Friday, `false` if not
saturday	Boolean	`true` if this schedule blocks on Saturday, `false` if not
start_timestamp	Time	The start of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
end_timestamp	Time	The end of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
user_ids	Array	An array of user IDs that this blocker should apply to
start	Date	The start date for this blocker
weeks	Integer	The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.
repetitions	Integer	How many times this blocker repeats. Ignored if `infinite_repetitions` is true
infinite_repetitions	Boolean	If this is `true`, this blocker repeats forever

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "brunch",
    "sunday": false,
    "monday": true,
    "tuesday": false,
    "wednesday": false,
    "thursday": false,
    "friday": false,
    "saturday": false,
    "start_timestamp": "13:55",
    "end_timestamp": "14:30",
    "user_ids": [
      1
    ],
    "start": "2017-01-01",
    "weeks": 1,
    "repetitions": 1,
    "infinite_repetitions": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Get an individual schedule day/time

Get an individual schedule day/time

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days/:id

Parameter

Field	Type	Description
schedule_id	Number	The ID of the schedule that contains this day/time
id	Number	The ID of the schedule day/time

Success 200

Field	Type	Description
id	Number	The ID of the schedule day/time.
day	Number	The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.
start_timestamp	Time	The starting time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.
end_timestamp	Time	The ending time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 9,
     "day": 1,
     "start_timestamp": "00:00",
     "end_timestamp": "23:00"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Get an individual schedule

Get an individual schedule

https://example.sonar.software/api/v1/scheduling/schedules/:id

Parameter

Field	Type	Description
id	Number	The ID of the schedule

Success 200

Field	Type	Description
id	Number	The ID of the schedule.
name	String	The name of the schedule
user_ids	Array	An array of user IDs that this schedule is applied to
job_type_ids	Array	An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container
start	Date	The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.
available	Boolean	Whether this schedule defines availability, or lack of availability.
infinite_repetitions	Boolean	Will be `true` if this schedule runs indefinitely
repetitions	Number	How many times this schedule should repeat.
weeks	Number	How often the repetition should occur, in weeks.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "user_ids": [ 1 ],
    "job_type_ids": [ 1, 2 ],
    "name": "Test",
    "start": "2016-08-05",
    "available": true,
    "infinite_repetitions": false,
    "repetitions": 1,
    "weeks": 3
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Get an individual scheduled time off

Get an individual scheduled time off

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs/:id

Parameter

Field	Type	Description
id	Integer	The ID of the scheduled time off

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled time off.
user_id	Integer	The ID of the user that has time off scheduled
start_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
end_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
name	String	A description/reason for the time off.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "user_id": 1,
    "start_time": "2016-11-01 01:00:00",
    "end_time": "2016-11-01 01:30:00"
    "name": "test"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Get the calculated schedule for a date range

This function will calculate out the availability for all scheduled users, between :start_date and :end_date. It will also include all jobs scheduled within those times. This is a fairly complex data structure that is designed to be used to allow easier integration into external display/scheduling systems.

https://example.sonar.software/api/v1/scheduling/calculated_schedule/:start_date/:end_date

Parameter

Field	Type	Description
start_date	Date	The start date for this query, in the system timezone.
end_date	Date	The end date for this query, in the system timezone.

Success 200

Field	Type	Description
Schedule	Array	The format of the data is shown below. The first property is the date. Within that object, the properties are the user IDs. Within the user object, there is a `schedule` array, a `jobs` array, and a `schedule_blockers` array. The `schedule` array contains a list of available time for the date referenced at the top level, where the property is the job type ID the times are for, and the value is an array of times. The `jobs` array contains a list of jobs scheduled for that day, formatted in the same manner as jobs queried from the jobs endpoint. The `schedule_blockers` array contains objects that represent configured schedule blockers. These show the start and end time for the blocker, the name, and the schedule blocker ID. If the blocker has been overridden, then the `overridden` property will be `true`. The `uniqueid` property within this object is just a way for you to uniquely identify blockers in an external application if needed, and can otherwise be ignored.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "2017-02-06": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "23:59"
            }
          ]
        },
        "jobs": [
          {
            "id": 2,
            "scheduled_datetime": "2017-02-06 12:53",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 1,
            "notes": "",
            "status": "scheduled",
            "user_ids": [
              1
            ],
            "created_by_user_id": 1,
            "checked_in_users": [],
            "services": []
          },
          {
            "id": 5,
            "scheduled_datetime": "2017-02-06 17:43",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 35,
            "notes": "",
            "status": "scheduled",
            "user_ids": [
              1
            ],
            "created_by_user_id": 1,
            "checked_in_users": [],
            "services": []
          },
          {
            "id": 4,
            "scheduled_datetime": "2017-02-06 08:00",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 35,
            "notes": "",
            "status": "scheduled",
            "user_ids": [
              1
            ],
            "created_by_user_id": 1,
            "checked_in_users": [],
            "services": []
          }
        ],
        "schedule_blockers": [
          {
            "start": "10:30",
            "end": "11:30",
            "name": "Brunch",
            "id": 2,
            "overridden": true,
            "uniqueid": "2_1"
          },
          {
            "start": "00:00",
            "end": "00:45",
            "name": "Break",
            "id": 7,
            "overridden": false,
            "uniqueid": "7_1"
          },
          {
            "start": "00:00",
            "end": "00:30",
            "name": "Lunch",
            "id": 8,
            "overridden": false,
            "uniqueid": "8_1"
          }
        ]
      }
    },
    "2017-02-07": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "23:59"
            }
          ]
        },
        "jobs": [],
        "schedule_blockers": [
          {
            "start": "00:00",
            "end": "00:45",
            "name": "Break",
            "id": 7,
            "overridden": false,
            "uniqueid": "7_1"
          },
          {
            "start": "00:00",
            "end": "00:30",
            "name": "Lunch",
            "id": 8,
            "overridden": false,
            "uniqueid": "8_1"
          }
        ]
      }
    }
  }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the schedule day/time could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "schedule day/time does not exist.",
         "status_code": 404
     }
 }

Schedules - Get the calculated schedule for a date range

https://example.sonar.software/api/v1/scheduling/calculated_schedule/:start_date/:end_date

Parameter

Field	Type	Description
start_date	Date	The start date for this query, in the system timezone.
end_date	Date	The end date for this query, in the system timezone.

Success 200

Field	Type	Description
Schedule	Array	The format of the data is shown below. The first property is the date. Within that object, the properties are the user IDs. Within the user object, there is a `schedule` array and a `jobs` array. The `schedule` array contains a list of available time for the date referenced at the top level, where the property is the job type ID the times are for, and the value is an array of times. The `jobs` array contains a list of jobs scheduled for that day, formatted in the same manner as jobs queried from the jobs endpoint.

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "2016-08-21": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "01:00"
            }
          ],
          "2": []
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "01:00"
            }
          ],
          "2": []
        },
        "jobs": []
      }
    },
    "2016-08-22": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ],
          "2": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ]
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ],
          "2": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ]
        },
        "jobs": []
      }
    },
    "2016-08-26": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "04:00",
              "end": "10:00"
            },
            {
              "start": "15:00",
              "end": "21:00"
            }
          ],
          "2": []
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "04:00",
              "end": "10:00"
            },
            {
              "start": "15:00",
              "end": "21:00"
            }
          ],
          "2": []
        },
        "jobs": []
      }
    },
    "2016-08-28": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "01:00"
            }
          ],
          "2": []
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "01:00"
            }
          ],
          "2": []
        },
        "jobs": []
      }
    },
    "2016-08-29": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ],
          "2": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ]
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ],
          "2": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ]
        },
        "jobs": [
          {
            "id": 31,
            "scheduled_datetime": "2016-08-29 11:00",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "drive_time_in_minutes": 0,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 1,
            "notes": "Please replace the router.",
            "status": "scheduled",
            "user_ids": [
              2
            ],
            "created_by_user_id": 0,
            "checked_in_users": [],
            "services": []
          },
          {
            "id": 32,
            "scheduled_datetime": "2016-08-29 10:00",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "drive_time_in_minutes": 0,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 1,
            "notes": "Please replace the switch.",
            "status": "scheduled",
            "user_ids": [
              2
            ],
            "created_by_user_id": 0,
            "checked_in_users": [],
            "services": []
          }
        ]
      }
    }
  }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the schedule day/time could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "schedule day/time does not exist.",
         "status_code": 404
     }
 }

Schedules - Override a schedule blocker

Override a schedule blocker for a single user

https://example.sonar.software/api/v1/scheduling/schedule_blockers/:id/schedule_blocker_overrides

Parameter

Field	Type	Description
id	Integer	The ID of the blocker
date	Date	The date you wish to override the blocker for
start_timestamp	Time	The start of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
end_timestamp	Time	The end of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
user_id	Integer	The ID of the user you wish to override the blocker time for

Success 200

Field	Type	Description
id	Integer	The ID of the blocker
date	Date	The date you wish to override the blocker for
start_timestamp	Time	The start of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
end_timestamp	Time	The end of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
user_id	Integer	The ID of the user you wish to override the blocker time for

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "date": "2017-02-06",
    "start_timestamp": "10:30",
    "end_timestamp": "11:30",
    "user_id": "1",
    "schedule_blocker_id": 2
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Update schedule blocker

Update an existing schedule blocker.

https://example.sonar.software/api/v1/scheduling/schedule_blockers/:id

Parameter

Field	Type	Description
id	Integer	The ID of the blocker
name	String	A name for the schedule blocker
sunday	Boolean	`true` if this schedule blocks on Sunday, `false` if not
monday	Boolean	`true` if this schedule blocks on Monday, `false` if not
tuesday	Boolean	`true` if this schedule blocks on Tuesday, `false` if not
wednesday	Boolean	`true` if this schedule blocks on Wednesday, `false` if not
thursday	Boolean	`true` if this schedule blocks on Thursday, `false` if not
friday	Boolean	`true` if this schedule blocks on Friday, `false` if not
saturday	Boolean	`true` if this schedule blocks on Saturday, `false` if not
start_timestamp	Time	The start of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
end_timestamp	Time	The end of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
user_ids	Array	An array of user IDs that this blocker should apply to
start	Date	The start date for this blocker
weeks	Integer	The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.
repetitions	Integer	How many times this blocker repeats. Ignored if `infinite_repetitions` is true
infinite_repetitions	Boolean	If this is `true`, this blocker repeats forever

Success 200

Field	Type	Description
id	Integer	The ID of the blocker
name	String	A name for the schedule blocker
sunday	Boolean	`true` if this schedule blocks on Sunday, `false` if not
monday	Boolean	`true` if this schedule blocks on Monday, `false` if not
tuesday	Boolean	`true` if this schedule blocks on Tuesday, `false` if not
wednesday	Boolean	`true` if this schedule blocks on Wednesday, `false` if not
thursday	Boolean	`true` if this schedule blocks on Thursday, `false` if not
friday	Boolean	`true` if this schedule blocks on Friday, `false` if not
saturday	Boolean	`true` if this schedule blocks on Saturday, `false` if not
start_timestamp	Time	The start of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
end_timestamp	Time	The end of the blocker, expressed as H:m where `H` is in 24 hour time, and `m` is minutes (e.g. 13:40)
user_ids	Array	An array of user IDs that this blocker should apply to
start	Date	The start date for this blocker
weeks	Integer	The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.
repetitions	Integer	How many times this blocker repeats. Ignored if `infinite_repetitions` is true
infinite_repetitions	Boolean	If this is `true`, this blocker repeats forever

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Integer	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Update schedule day/time

Update an existing schedule day/time.

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days/:id

Parameter

Field	Type	Description
schedule_id	Number	The ID of the schedule that contains this day/time
id	Number	The schedule day/time ID
day optional	Number	The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday. Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6`
start_timestamp optional	Time	The starting time for this particular period, in Hour:Minute format, where minute must be in 15 minute increments. This is in the Sonar timezone, not UTC.
end_timestamp optional	Time	The ending time for this particular period, in Hour:Minute format, where minute must be in 15 minute increments. This is in the Sonar timezone, not UTC.

Success 200

Field	Type	Description
id	Number	The ID of the schedule day/time.
day	Number	The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.
start_timestamp	Time	The starting time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.
end_timestamp	Time	The ending time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
     "id": 9,
     "day": 1,
     "start_timestamp": "00:00",
     "end_timestamp": "23:00"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Update schedule

Update an existing schedule.

https://example.sonar.software/api/v1/scheduling/schedules/:id

Parameter

Field	Type	Description
name optional	String	A name for the schedule
user_ids optional	Array	An array of user IDs that this schedule is applied to
job_type_ids optional	Array	An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container
start optional	Date	The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.
available optional	Boolean	Whether this schedule defines availability, or lack of availability. A schedule with `available` set to `false` will always override another schedule with `available` set to `true`.
infinite_repetitions optional	Boolean	Set this to `true` if you want this schedule to run indefinitely
repetitions optional	Number	How many times this schedule should repeat. 0 to never repeat. You can set this to a high number to repeat indefinitely (e.g. 2147483647)
weeks optional	Number	How often the repetition should occur, in weeks. If this is 1, this schedule repeats every week. If this is 2, the schedule runs for one week, then breaks for one week, then runs for one week, then breaks for one week, etc. If this is 3, the schedule runs for one week, then breaks for two weeks, then runs for one week, then breaks for two weeks, etc. This interacts with `repetitions` by repeating `repetitions` times for the number of active weeks. For example, if weeks is 2, and repetitions is 1, this schedule would run for a week, skip a week, run for a week, and then stop.

Success 200

Field	Type	Description
id	Number	The ID of the schedule.
name	String	The name of the schedule
user_ids	Array	An array of user IDs that this schedule is applied to
job_type_ids	Array	An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container
start	Date	The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.
available	Boolean	Whether this schedule defines availability, or lack of availability.
infinite_repetitions	Boolean	Will be `true` if this schedule runs indefinitely
repetitions	Number	How many times this schedule should repeat.
weeks	Number	How often the repetition should occur, in weeks.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 6,
    "user_ids": [ 1 ],
    "job_type_ids": [ 1, 2, 3 ],
    "name": "Test",
    "start": "2016-08-05",
    "available": true,
    "infinite_repetitions": true,
    "repetitions": 1,
    "weeks": 3
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Update scheduled time off

Update an existing scheduled time off.

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs/:id

Parameter

Field	Type	Description
user_id optional	Integer	The ID of the user that has time off scheduled
start_time optional	DateTime	The day and time that the user has scheduled off, in the system timezone.
end_time optional	DateTime	The day and time that the user has scheduled off, in the system timezone.
name optional	String	A description/reason for the time off.

Success 200

Field	Type	Description
id	Integer	The ID of the scheduled time off.
user_id	Integer	The ID of the user that has time off scheduled
start_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
end_time	DateTime	The day and time that the user has scheduled off, in the system timezone.
name	String	A description/reason for the time off.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "user_id": 1,
    "start_time": "2016-11-01 01:00:00",
    "end_time": "2016-11-01 02:00:00",
    "name": "Update me"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Search

Search - Search for specific entities

The search endpoint supports a number of complex operations, and can be used to search for data within your Sonar instance. The format of data returned from this endpoint for each entity is not fully documented here, and may be subject to change - do not rely on the data format of this endpoint being consistent across versions! All data from this endpoint is paginated and limited by size.

Generally speaking, if you want to implement this data into an external system, you should use this endpoint to search for the particular ID you need, and then perform a GET to the appropriate endpoint to get the consistently formatted data. However, the data format returned here can be useful if you're building some kind of search display page.

There are a number of parameters that can be passed in here to search for data in very specific ways. Each parameter can be used in tandem with other parameters to return very precise results.

Every result will contain a datetime property, which is the date and time in system timezone that the entity was created. All fields that contain a date and time will be returned in the system timezone, formatted into the selected datetime format. However, there will always be an unformatted field in the _$FIELDNAME_unformatted property (e.g. _datetime_unformatted) as an ISO8601 string.

Please see the examples below for more details.

https://example.sonar.software/api/v1/search/:entity/

{
	"size": 100,
	"page": 1,
	"search": {
		"search": "Activ" //Find anything matching the partial string 'Activ'
	}
}

{
	"size": 100,
	"page": 1,
	"search": {
		"fields": {
			"name": "Activation", //Find anything where the 'name' property has the full word 'Activation' in it
			"account_type_id": 1 //Find all accounts with an account_type_id of 1. Both of these parameters must match.
		}
	}
}

{
	"size": 100,
	"page": 1,
	"search": {
		"fields": {
			"name": "Activation",  //Find anything where the 'name' property has the full word 'Activation' in it
			"account_type_id": 1,  //Find all accounts with an account_type_id of 1.
			"tax_exempt": null //Normally, this would be discarded, but because 'parse_nulls_fields' has this field name in it, this will only return entries where tax_exempt is explicitly null. All three of these values must be matched.
		},
		"parse_nulls_fields": [
			"tax_exempt" //See the 'fields' property above
		],
		"quantity_based_match": [
		    {
		        "fields": {
		            "id": 2 //ID must be 2
		            "delinquent": false //Delinquent must be false
		        },
		        "minimum_should_match": 1 //Only one of the requirements in 'fields' must match
		    }
		],
		"quantity_based_exists": {
			"fields": [
			    "next_bill_date", //next_bill_date must not be null
				"name", //name must not be null
				"delinquent" //delinquent must not be null
			],
			"minimum_should_exists": 2 //At least 2 of the 'fields' properties above must exist/not be null
		},
		"not_fields": {
			"delinquent": true //Delinquent must not be true
		},
		"date_limits": [
		    {
		        "field": "datetime",
		        "from": "1970-01-01 00:00:00",
		        "to": "2017-01-01 00:00:00"
		    }
		]
	}
}

Parameter

Field	Type	Description
entity	String	A valid entity to search for. See the other API endpoints to determine the proper naming convention here. For example, to search accounts, enter `accounts`. To search invoices, enter `invoices`. To search network sites, enter `network_sites`.
size	Number	The number of entries to return
page	Number	The page of results to return
group_by optional	Array	An array of field names to group by. This will return a count of all results, grouped by that field name, in addition to the normal results.
return_all_ids optional	Boolean	If this is set to true, then the search results will return all entity IDs that match your parameters, ignoring all pagination. For example, if there are 10,000 results, and your size parameter is `100`, the results would only contain 100 entries at a time, but the results will also contain a `all_ids` property that contains a list of all 10,000 matching entity IDs. Use this parameter with caution! Default value: `false`
search optional	Object	An object containing a list of search parameters. All parameters below this line must be contained within the `search` object.. This object may also contain a `search` property, which is a simple string to search all indexed fields for. This can match on partial strings.
fields optional	Object	An object where the value is the data you wish to search for, and the property is the name of the field. The value must be a string. This will work on exact matches on full words only - e.g. 'Simon' will match 'Simon Westlake' but not 'Simonis'. If you want to search for partial matches, use the `search` property within the master `search` object (see example for details.)
parse_nulls_fields optional	Array	An array containing a list of field names. In the `fields` parameter above, any value entered as `null` or an empty string is silently discarded. If you explicitly name a field in this parameter, then searching for an empty string or `null` in the `fields` parameter will explicitly return results where that field is `null` or an empty string.
quantity_based_match optional	Array	An array of objects, each of which has a `fields` parameter, which is formatted in the same manner as the `fields` parameter described above. This object should also contain a `minimum_should_match` property, which is an integer. This defines how many of the search terms you have described in this property must match. Each object will be independently evaluated.
quantity_based_exists optional	Object	An object where the `fields` property is an array of fields that must exist in the result (e.g. are not null or an empty string.) This object should also contain a `minimum_should_exist` property, which is an integer. This defines how many of the search terms you have described in this property must exist.
not_fields optional	Array	An array formatted identically to the `fields` parameter described above. This contains a list of fields and values that must not match in the result.
date_limits optional	Array	You can use this to limit results to items within a certain date range. This can only be used on fields that are represented as a date field. Do not reference fields here with the format _fieldname_unformatted, where _fieldname is a fieldname. Submit an object with three parameters - 'field', which is the field name to filter on, 'from', which is the start date/time, and 'to', which is the end date/time. These dates/times should be in the system timezone. At least one of 'from' and 'to' must be present for this filter to be applied. Bear in mind that most date fields that do not have the `_unformatted` suffix are represented in the system timezone.

Success-Response:

{
    "data": {
        "results": {
            "0": {
                "name": "Activation Testing",
                "account_status_id": 2,
                "account_type_id": 1,
                "tax_exempt": null,
                "activation_date": "Dec 12, 2016 08:09:47",
                "next_bill_date": "Jan 12, 2017",
                "last_billed_invoice_id": null,
                "master_account_id": null,
                "delinquent": false,
                "delinquency_date": null,
                "datetime": "Dec 12, 2016 14:09:00",
                "id": 2,
                "addresses": [
                    {
                        "zip": "27000",
                        "country": "TR",
                        "address_type": "physical",
                        "city": "Test",
                        "latitude": 37.26306,
                        "county": null,
                        "address_type_id": 1,
                        "datetime": "2016-12-12T20:09:00+0000",
                        "state": "Gaziantep",
                        "id": 4,
                        "line2": "",
                        "line1": "Unnamed Road",
                        "longitude": 37.26306
                    }
                ],
                "_activation_date_unformatted": "2016-12-12T14:09:47+0000",
                "_next_bill_date_unformatted": "2017-01-12",
                "_datetime_unformatted": "2016-12-12T20:09:00+0000",
                "_uid": "accounts_2"
            },
            "aggregations": []
        },
        "paginator": {
            "current_page": 1,
            "limit": 100,
            "total_pages": 1,
            "total_count": 1
        }
    }
}

Services

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
id optional	Integer	The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, overage, or recurring, defines what type of service this is Allowed values: `"one time"`, `"recurring"`, `"expiring"`, `"adjustment"`, `"overage"`
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true.
unit_quantity_in_gigabytes optional	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if `type` is overage.
general_ledger_code_id optional	Integer	The ID of the general ledger code you wish to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to `25`. Should be omitted in cases where the entirety of the service is taxable.
voice_service optional	Boolean	Whether or not this is a voice service
unlimited_local_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes optional	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount optional	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes optional	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount optional	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes optional	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate optional	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls
account_groups optional	Array	An array of account group IDs

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls
account_groups	Array	An array of account group IDs

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "billing_frequency_in_months": 1,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null,
         "account_groups": []
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
id optional	Integer	The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, overage, or recurring, defines what type of service this is Allowed values: `"one time"`, `"recurring"`, `"expiring"`, `"adjustment"`, `"overage"`
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true.
unit_quantity_in_gigabytes optional	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if `type` is overage.
general_ledger_code_id optional	Integer	The ID of the general ledger code you wish to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to `25`. Should be omitted in cases where the entirety of the service is taxable.
voice_service optional	Boolean	Whether or not this is a voice service
unlimited_local_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes optional	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount optional	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes optional	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount optional	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes optional	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate optional	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "billing_frequency_in_months": 1,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
id optional	Integer	The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, overage, or recurring, defines what type of service this is Allowed values: `"one time"`, `"recurring"`, `"expiring"`, `"adjustment"`, `"overage"`
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true.
unit_quantity_in_gigabytes optional	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if `type` is overage.
general_ledger_code_id optional	Integer	The ID of the general ledger code you wish to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to `25`. Should be omitted in cases where the entirety of the service is taxable.
voice_service optional	Boolean	Whether or not this is a voice service
unlimited_local_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes optional	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount optional	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes optional	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount optional	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes optional	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate optional	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, overage, or recurring, defines what type of service this is Allowed values: `"one time"`, `"recurring"`, `"expiring"`, `"adjustment"`, `"overage"`
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true.
unit_quantity_in_gigabytes optional	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if `type` is overage.
general_ledger_code_id optional	Integer	The ID of the general ledger code you wish to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to `25`. Should be omitted in cases where the entirety of the service is taxable.
voice_service optional	Boolean	Whether or not this is a voice service
unlimited_local_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes optional	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount optional	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes optional	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount optional	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes optional	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate optional	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, overage, or recurring, defines what type of service this is Allowed values: `"one time"`, `"recurring"`, `"expiring"`, `"adjustment"`, `"overage"`
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true.
unit_quantity_in_gigabytes optional	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if `type` is overage.
general_ledger_code_id optional	Integer	The ID of the general ledger code you wish to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $60, but only $35 of it is taxable, set this to `25` (60-35 = 25.) Should be omitted in cases where the entirety of the service is taxable.

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service to exempt from taxation

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, overage, or recurring, defines what type of service this is Allowed values: `"one time"`, `"recurring"`, `"expiring"`, `"adjustment"`, `"overage"`
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true.
unit_quantity_in_gigabytes optional	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if `type` is overage.
general_ledger_code_id optional	Integer	The ID of the general ledger code you wish to assign to this service

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring or recurring, defines what type of service this is Allowed values: `"one time"`, `"recurring"`, `"expiring"`, `"adjustment"`
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "active": true,
    "name": "Schumm Ltd",
    "type": "recurring",
    "application": "debit",
    "amount": 63.62,
    "times_to_run": 4,
    "limit_adjustments": false,
    "period_days": 0,
    "max_amount_per_period": "0.00",
    "taxes": [],
    "roles": [],
    "data_service": true,
    "upload_in_kilobits": 500,
    "download_in_kilobits": 1000,
    "technology_code": 70
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring or recurring, defines what type of service this is Allowed values: `"one time"`, `"recurring"`, `"expiring"`, `"adjustment"`
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "Gleichner-Rowe",
    "type": "expiring",
    "application": "debit",
    "amount": 21.30,
    "times_to_run": 6,
    "limit_adjustments": false,
    "period_days": 0,
    "max_amount_per_period": "0.00",
    "taxes": [
      1
    ],
    "roles": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Delete service

Delete a service. Be careful when using this method! Deletion will permanently disassociate the service from all accounts, packages and roles.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The ID of the service

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the service could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "That service does not exist.",
         "status_code": 404
     }
 }

Services - Get all services

https://example.sonar.software/api/v1/system/services

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls
account_groups optional	Array	An array of account group IDs

Success-Response:

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "billing_frequency_in_months": 1,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 70,
             "usage_based_billing_policy_id": 1,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null,
             "account_groups": []
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

https://example.sonar.software/api/v1/system/services

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "billing_frequency_in_months": 1,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 70,
             "usage_based_billing_policy_id": 1,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 1,
             "active": true,
             "name": "Bauch Group",
             "type": "expiring",
             "application": "debit",
             "amount": 53.74,
             "times_to_run": 5,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [
             1
             ],
             "roles": [],
             "data_service": false,
             "upload_in_kilobits": 0,
             "download_in_kilobits": 0,
             "technology_code": 0,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": null,
             "tax_exemption_amount": 25,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null
         },
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 40,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, adjustment or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid on debit services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service to exempt from taxation

Success-Response:

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 1,
             "active": true,
             "name": "Bauch Group",
             "type": "expiring",
             "application": "debit",
             "amount": 53.74,
             "times_to_run": 5,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [
             1
             ],
             "roles": [],
             "data_service": false,
             "upload_in_kilobits": 0,
             "download_in_kilobits": 0,
             "technology_code": 0,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": null,
             "tax_exemption_amount": 25
         },
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 40,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, adjustment or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid on debit services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service

Success-Response:

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 1,
             "active": true,
             "name": "Bauch Group",
             "type": "expiring",
             "application": "debit",
             "amount": 53.74,
             "times_to_run": 5,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [
             1
             ],
             "roles": [],
             "data_service": false,
             "upload_in_kilobits": 0,
             "download_in_kilobits": 0,
             "technology_code": 0,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": null
         },
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 40,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, adjustment or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid on debit services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
    {
        "id": 1,
        "active": true,
        "name": "Bauch Group",
        "type": "expiring",
        "application": "debit",
        "amount": 53.74,
        "times_to_run": 5,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [
        1
        ],
        "roles": [],
        "data_service": false,
        "upload_in_kilobits": 0,
        "download_in_kilobits": 0,
        "technology_code": 0
    },
    {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40
    },
    ],
    "paginator": {
        "total_count": 30,
        "total_pages": 15,
        "current_page": 1,
        "limit": 2
    }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, expiring, adjustment or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid on debit services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
        {
         "id": 1,
         "active": true,
         "name": "Gleichner-Rowe",
         "type": "expiring",
         "application": "debit",
         "amount": 21.30,
         "times_to_run": 6,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [
           1
         ],
         "roles": []
       },
       {
         "id": 2,
         "active": true,
         "name": "Balistreri Group",
         "type": "recurring",
         "application": "credit",
         "amount": 71.51,
         "times_to_run": 6,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [
           1
         ],
         "roles": []
       },
    ],
    "paginator": {
        "total_count": 30,
        "total_pages": 15,
        "current_page": 1,
        "limit": 2
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls
account_groups optional	Array	An array of account group IDs

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "billing_frequency_in_months": 1,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 70,
             "usage_based_billing_policy_id": 1,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null,
             "account_groups": []
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "billing_frequency_in_months": 1,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 70,
             "usage_based_billing_policy_id": 1,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 50,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 12,
        "tax_exemption_amount": 0,
        "voice_service": false,
        "unlimited_local_minutes": false,
        "unlimited_long_distance_minutes": false,
        "local_minutes": null,
        "local_minutes_amount": 0,
        "long_distance_minutes": null,
        "long_distance_minutes_amount": 0,
        "first_interval_in_seconds": null,
        "sub_interval_in_seconds": null,
        "local_prefixes": [],
        "inbound_toll_free_rate": null
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid for debit services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service to exempt from taxation

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 50,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 12,
        "tax_exemption_amount": 0
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid for debit services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 50,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 12
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid for debit services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 50
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid for debit services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "Gleichner-Rowe",
    "type": "expiring",
    "application": "debit",
    "amount": 21.30,
    "times_to_run": 6,
    "limit_adjustments": false,
    "period_days": 0,
    "max_amount_per_period": "0.00",
    "taxes": [
      1
    ],
    "roles": []
  }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id optional	Integer	The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true.
unit_quantity_in_gigabytes optional	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if `type` is overage.
general_ledger_code_id optional	Integer	The ID of the general ledger code you wish to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to `25`. Should be omitted in cases where the entirety of the service is taxable.
voice_service optional	Boolean	Whether or not this is a voice service
unlimited_local_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes optional	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount optional	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes optional	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount optional	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes optional	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate optional	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls
account_groups optional	Array	An array of account group IDs

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls
account_groups optional	Array	An array of account group IDs

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "billing_frequency_in_months": 1,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null,
         "account_groups": [ 1 ]
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id optional	Integer	The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true.
unit_quantity_in_gigabytes optional	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if `type` is overage.
general_ledger_code_id optional	Integer	The ID of the general ledger code you wish to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to `25`. Should be omitted in cases where the entirety of the service is taxable.
voice_service optional	Boolean	Whether or not this is a voice service
unlimited_local_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes optional	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount optional	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes optional	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount optional	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes optional	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate optional	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
billing_frequency_in_months	Integer	How often this service bills, `1` for monthly, `12` for annually, etc. Only valid for recurring services.
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "billing_frequency_in_months": 1,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The internal ID of the service
active optional	Boolean	Whether or not this service can still be added to accounts
name optional	String	A descriptive name for the service
application optional	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount optional	Number	The amount the service costs
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
general_ledger_code_id optional	Integer	The ID of the general ledger code to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to `25`. Should be omitted in cases where the entirety of the service is taxable.
voice_service optional	Boolean	Whether or not this is a voice service
unlimited_local_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes optional	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes optional	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount optional	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes optional	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount optional	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds optional	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes optional	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate optional	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation
voice_service	Boolean	Whether or not this is a voice service
unlimited_local_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited local minutes
unlimited_long_distance_minutes	Boolean	If this is a voice service, this describes whether the voice service offers unlimited long distance minutes
local_minutes	Integer	If unlimited_local_minutes is false, this is the number of free local minutes provided with the service
local_minutes_amount	Number	If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.
long_distance_minutes	Integer	If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service
long_distance_minutes_amount	Number	If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.
first_interval_in_seconds	Integer	If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.
sub_interval_in_seconds	Integer	If this is a voice service, this is the minimum time per block after the `first_interval_in_seconds`. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.
local_prefixes	Array	If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.
inbound_toll_free_rate	Number	If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm's Super Internet",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 1,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 1,
        "tax_exemption_amount": 0,
        "voice_service": false,
        "unlimited_local_minutes": false,
        "unlimited_long_distance_minutes": false,
        "local_minutes": null,
        "local_minutes_amount": 0,
        "long_distance_minutes": null,
        "long_distance_minutes_amount": 0,
        "first_interval_in_seconds": null,
        "sub_interval_in_seconds": null,
        "local_prefixes": [],
        "inbound_toll_free_rate": null
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The internal ID of the service
active optional	Boolean	Whether or not this service can still be added to accounts
name optional	String	A descriptive name for the service
application optional	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount optional	Number	The amount the service costs
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
general_ledger_code_id optional	Integer	The ID of the general ledger code to assign to this service
tax_exemption_amount optional	Number	The amount of the service to exempt from taxation. For example, if this service costs $60, but only $35 of it is taxable, set this to `25` (60-35 = 25). Should be omitted or set to 0 in cases where the entirety of the service is taxable.

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service
tax_exemption_amount	Number	The amount of the service cost to exempt from taxation

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm's Super Internet",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 1,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 1,
        "tax_exemption_amount": 0
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The internal ID of the service
active optional	Boolean	Whether or not this service can still be added to accounts
name optional	String	A descriptive name for the service
application optional	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount optional	Number	The amount the service costs
times_to_run optional	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments optional	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days optional	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period optional	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes optional	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles optional	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service optional	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits optional	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits optional	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code optional	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id optional	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
general_ledger_code_id optional	Integer	The ID of the general ledger code to assign to this service

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring, overage, or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`
usage_based_billing_policy_id	Integer	The ID of the usage based billing policy applied to this service. Only valid if `data_service` is true
unit_quantity_in_gigabytes	Integer	If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount
general_ledger_code_id	Integer	The ID of the general ledger code assigned to this service

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm's Super Internet",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 1,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 1
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment
data_service	Boolean	Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)
download_in_kilobits	Integer	Only valid if data_service is true. The download speed of the service in kilobits per second.
upload_in_kilobits	Integer	Only valid if data_service is true. The upload speed of the service in kilobits per second.
technology_code	Integer	The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line. Default value: `0` Allowed values: `"0"`, `"10"`, `"20"`, `"30"`, `"40"`, `"50"`, `"60"`, `"70"`, `"90"`

Success-Response:

 HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm's Super Internet",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 1,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
         {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
application	String	One of credit or debit, defines whether or not the service applies or charge or a discount Allowed values: `"credit"`, `"debit"`
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

Success 200

Field	Type	Description
id	Number	The internal ID of the service
active	Boolean	Whether or not this service can still be added to accounts
name	String	A descriptive name for the service
type	String	One of one time, adjustment, expiring or recurring
application	String	One of credit or debit
amount	Number	The amount the service costs
times_to_run	Number	This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing
limit_adjustments	Boolean	This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored Default value: `false`
period_days	Number	This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value
max_amount_per_period	Number	This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days
taxes	Array	An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services
roles	Array	An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "Gleichner-Rowe",
    "type": "expiring",
    "application": "debit",
    "amount": 21.30,
    "times_to_run": 6,
    "limit_adjustments": false,
    "period_days": 0,
    "max_amount_per_period": "0.00",
    "taxes": [
      1
    ],
    "roles": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

System

System - Create account group

Create a new account group.

https://example.sonar.software/api/v1/system/account_groups

Parameter

Field	Type	Description
name	String	A unique name for the account group

Success 200

Field	Type	Description
id	Number	The ID of the account group, this can be used when setting an account group on an account
name	String	A descriptive name of the account group

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 6,
        "name": "People That I Like"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create account status

Create a new account status.

https://example.sonar.software/api/v1/system/account_statuses

Parameter

Field	Type	Description
name	String	A unique name for the account status
active	Boolean	Whether or not the status should activate customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application
account_super_user_only	Boolean	If this is `true`, only users in a role with the 'Account Super User' permission can set this status on an account

Success 200

Field	Type	Description
id	Number	The ID of the account status, this can be used when setting the account status on an account
name	String	A descriptive name of the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application
account_super_user_only	Boolean	If this is `true`, only users in a role with the 'Account Super User' permission can set this status on an account

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 5,
         "name": "Sent to Collections",
         "active": false,
         "color": "#00ffff",
         "account_super_user_only": true
     }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create account status

Create a new account status.

https://example.sonar.software/api/v1/system/account_statuses

Parameter

Field	Type	Description
name	String	A unique name for the account status
active	Boolean	Whether or not the status should activate customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application

Success 200

Field	Type	Description
id	Number	The ID of the account status, this can be used when setting the account status on an account
name	String	A descriptive name of the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 5,
         "name": "Sent to Collections",
         "active": false,
         "color": "#00ffff"
     }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create account type

Create a new account type.

https://example.sonar.software/api/v1/system/account_types

Parameter

Field Type Description

name

String

A unique name for the account type

type

String

The type of account type this is

Allowed values: "residential", "commercial"

Success 200

Field Type Description

Number

The ID of the account type, this can be used when setting the account type on an account

name

String

A descriptive name of the account type

type

String

The type of status this is

Allowed values: "residential", "commercial"

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
         "id": 12,
         "name": "My Custom Type",
         "type": "commercial"
     }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create address type

Create a new address type.

https://example.sonar.software/api/v1/system/address_types

Parameter

Field	Type	Description
name	String	A unique name for the address type

Success 200

Field	Type	Description
id	Number	The ID of the address type, this can be used when setting the address type on an address
name	String	A descriptive name of the address type

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 1,
        "name": "Physical"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create custom field

Create a new custom field.

https://example.sonar.software/api/v1/system/custom_fields

Parameter

Field	Type	Description
name	String	The name of the custom field
type	String	The type of field Allowed values: `"text"`, `"checkbox"`, `"select"`, `"date"`
unique	Boolean	Whether input to this custom field must be unique. Only applies to text fields and should not be submitted for other types
active	Boolean	If the field is not active, it won't show up on any entities that don't already have a value set
entity_type	String	The type of entity this custom field is displayed on Allowed values: `"account"`
select_options	Array	If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details. This field should not be submitted for other types

Success 200

Field	Type	Description
id	Number	The internal id of the custom field
name	String	The name of the custom field
type	String	The type of field Allowed values: `"text"`, `"checkbox"`, `"select"`, `"date"`
unique	Boolean	Whether input to this custom field must be unique. Only applies to text fields
active	Boolean	If the field is not active, it won't show up on any entities that don't already have a value set
entity_type	String	The type of entity this custom field is displayed on Allowed values: `"account"`
select_options	Array	If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details

Success-Response:

HTTP/1.1 201 OK
{
  "id": 8,
  "name": "Height of Antenna",
  "type": "text",
  "unique": true,
  "active": true,
  "entity_type": "account",
  "select_options": []
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The value entered for type is invalid."
         },
         "status_code": 422
     }
 }

System - Delete account group

Delete an account group.

https://example.sonar.software/api/v1/system/account_groups/:id

Parameter

Field	Type	Description
id	Number	The ID of the account group

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "Account group deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the account group could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Account group not found",
         "status_code": 404
     }
 }

System - Delete account status

Delete an account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "Account status deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the account status could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Account status not found",
         "status_code": 404
     }
 }

System - Delete account type

Delete an account types.

https://example.sonar.software/api/v1/system/account_types/:id

Parameter

Field	Type	Description
id	Number	The ID of the account type

Success 200

Field

Type

Description

message

String

A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the account type could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Account type not found",
         "status_code": 404
     }
 }

System - Delete address type

Delete an account type.

https://example.sonar.software/api/v1/system/address_types/:id

Parameter

Field	Type	Description
id	Number	The ID of the address type

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the account status could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Address type not found",
         "status_code": 404
     }
 }

System - Delete custom field

Delete a custom field. This will remove all data stored in this custom field from all entities also. If you just want to disable further use of the field, set the 'active' property to 'false'.

https://example.sonar.software/api/v1/system/custom_fields/:id

Parameter

Field	Type	Description
id	Number	The ID of the custom field

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the custom field could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Custom field does not exist.",
         "status_code": 404
     }
 }

System - Get KPIs and statistics

Get various key performance indicators and statistics. This data is collected in real time, so should be queried daily and stored if you want to track it over time.

https://example.sonar.software/api/v1/_data/kpi

Success 200

Field	Type	Description
active_accounts	Integer	The number of active accounts in the system.
delinquent_accounts	Integer	The number of delinquent accounts
all_accounts	Integer	A total count of accounts
invoiced_this_month	Float	The amount invoiced this month
total_due_balances	Float	A total of all due balances
undeposited_payments	Integer	A count of undeposited payments
invoices_to_print	Integer	The total count of invoices pending printing
open_public_tickets	Integer	The total open public tickets
open_internal_tickets	Integer	The total open internal tickets
tickets_by_group	Object	An object where the property is a ticket group ID and the value is the number of tickets open in that group
ticket_group_names	Object	A helper object that corresponds ticket group names to the IDs in tickets_by_group for easier display
count_of_accounts_status_changed_in_last_30_days	Integer	A count of accounts that have changed status in some way in the last 30 days
today	Object	An object, described directly below this entry, that contains various statistics that are only true for today
tickets	Integer	Tickets opened today
tickets_closed	Integer	Tickets closed today
payments	Float	The amount of all payments made today
payments_failed	Integer	A count of failed payments today
accounts	Integer	Accounts created today
debits	Float	The amount of all debits created today
discounts	Float	The amount of all discounts created today
customers_billed	Integer	A count of all customers billed today
accounts_activated	Integer	Accounts activated today
bounced_emails	Integer	A count of bounced emails today
contracts_expiring	Integer	A count of contracts expiring within 90 days
towercoverage_submissions_good	Integer	A count of accepted submissions from TowerCoverage.com today
towercoverage_submissions_bad	Integer	A count of rejected submissions from TowerCoverage.com today
jobs	Object	An object providing some information on jobs today, described below
scheduled	Integer	A count of jobs scheduled today
completed	Integer	A count of jobs completed today
failed	Integer	A count of jobs failed today
accounts_by_status_id	Object	An object where the property is the account status ID, and the value is the count of customers with that status ID.
arpu	Float	The average revenue per user

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "active_accounts": 1,
        "delinquent_accounts": 0,
        "all_accounts": 1,
        "invoiced_this_month": null,
        "total_due_balances": null,
        "undeposited_payments": 0,
        "invoices_to_print": 0,
        "open_public_tickets": 0,
        "open_internal_tickets": 0,
        "tickets_by_group": [],
        "ticket_group_names": [],
        "count_of_accounts_status_changed_in_last_30_days": 0,
        "today": {
            "tickets": 0,
            "tickets_closed": 0,
            "payments": "150.00",
            "payments_failed": 2,
            "accounts": 0,
            "debits": null,
            "discounts": null,
            "customers_billed": 0,
            "jobs": {
                "scheduled": 0,
                "completed": 0,
                "failed": 0
            },
            "accounts_activated": 0,
            "bounced_emails": 0,
            "contracts_expiring": 0,
            "towercoverage_submissions_good": 0,
            "towercoverage_submissions_bad": 0
        },
        "accounts_by_status_id": {
           "2": 1234,
           "5": 5678
           "12": 2
        },
        "arpu": 12.34
    }
}

System - Get KPIs and statistics

Get various key performance indicators and statistics. This data is collected in real time, so should be queried daily and stored if you want to track it over time.

https://example.sonar.software/api/v1/_data/kpi

Success 200

Field	Type	Description
active_accounts	Integer	The number of active accounts in the system.
delinquent_accounts	Integer	The number of delinquent accounts
all_accounts	Integer	A total count of accounts
invoiced_this_month	Float	The amount invoiced this month
total_due_balances	Float	A total of all due balances
undeposited_payments	Integer	A count of undeposited payments
invoices_to_print	Integer	The total count of invoices pending printing
open_public_tickets	Integer	The total open public tickets
open_internal_tickets	Integer	The total open internal tickets
tickets_by_group	Object	An object where the property is a ticket group ID and the value is the number of tickets open in that group
ticket_group_names	Object	A helper object that corresponds ticket group names to the IDs in tickets_by_group for easier display
count_of_accounts_status_changed_in_last_30_days	Integer	A count of accounts that have changed status in some way in the last 30 days
today	Object	An object, described directly below this entry, that contains various statistics that are only true for today
tickets	Integer	Tickets opened today
tickets_closed	Integer	Tickets closed today
payments	Float	The amount of all payments made today
payments_failed	Integer	A count of failed payments today
accounts	Integer	Accounts created today
debits	Float	The amount of all debits created today
discounts	Float	The amount of all discounts created today
customers_billed	Integer	A count of all customers billed today
accounts_activated	Integer	Accounts activated today
bounced_emails	Integer	A count of bounced emails today
contracts_expiring	Integer	A count of contracts expiring within 90 days
towercoverage_submissions_good	Integer	A count of accepted submissions from TowerCoverage.com today
towercoverage_submissions_bad	Integer	A count of rejected submissions from TowerCoverage.com today
jobs	Object	An object providing some information on jobs today, described below
scheduled	Integer	A count of jobs scheduled today
completed	Integer	A count of jobs completed today
failed	Integer	A count of jobs failed today
accounts_by_status_id	Object	An object where the property is the account status ID, and the value is the count of customers with that status ID.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "active_accounts": 1,
        "delinquent_accounts": 0,
        "all_accounts": 1,
        "invoiced_this_month": null,
        "total_due_balances": null,
        "undeposited_payments": 0,
        "invoices_to_print": 0,
        "open_public_tickets": 0,
        "open_internal_tickets": 0,
        "tickets_by_group": [],
        "ticket_group_names": [],
        "count_of_accounts_status_changed_in_last_30_days": 0,
        "today": {
            "tickets": 0,
            "tickets_closed": 0,
            "payments": "150.00",
            "payments_failed": 2,
            "accounts": 0,
            "debits": null,
            "discounts": null,
            "customers_billed": 0,
            "jobs": {
                "scheduled": 0,
                "completed": 0,
                "failed": 0
            },
            "accounts_activated": 0,
            "bounced_emails": 0,
            "contracts_expiring": 0,
            "towercoverage_submissions_good": 0,
            "towercoverage_submissions_bad": 0
        },
        "accounts_by_status_id": {
           "2": 1234,
           "5": 5678
           "12": 2
        }
    }
}

System - Get KPIs and statistics

Get various key performance indicators and statistics. This data is collected in real time, so should be queried daily and stored if you want to track it over time.

https://example.sonar.software/api/v1/_data/kpi

Success 200

Field	Type	Description
active_accounts	Integer	The number of active accounts in the system.
delinquent_accounts	Integer	The number of delinquent accounts
all_accounts	Integer	A total count of accounts
invoiced_this_month	Float	The amount invoiced this month
total_due_balances	Float	A total of all due balances
undeposited_payments	Integer	A count of undeposited payments
invoices_to_print	Integer	The total count of invoices pending printing
open_public_tickets	Integer	The total open public tickets
open_internal_tickets	Integer	The total open internal tickets
tickets_by_group	Object	An object where the property is a ticket group ID and the value is the number of tickets open in that group
ticket_group_names	Object	A helper object that corresponds ticket group names to the IDs in tickets_by_group for easier display
count_of_accounts_status_changed_in_last_30_days	Integer	A count of accounts that have changed status in some way in the last 30 days
today	Object	An object, described directly below this entry, that contains various statistics that are only true for today
tickets	Integer	Tickets opened today
tickets_closed	Integer	Tickets closed today
payments	Float	The amount of all payments made today
payments_failed	Integer	A count of failed payments today
accounts	Integer	Accounts created today
debits	Float	The amount of all debits created today
discounts	Float	The amount of all discounts created today
customers_billed	Integer	A count of all customers billed today
accounts_activated	Integer	Accounts activated today
bounced_emails	Integer	A count of bounced emails today
contracts_expiring	Integer	A count of contracts expiring within 90 days
towercoverage_submissions_good	Integer	A count of accepted submissions from TowerCoverage.com today
towercoverage_submissions_bad	Integer	A count of rejected submissions from TowerCoverage.com today
jobs	Object	An object providing some information on jobs today, described below
scheduled	Integer	A count of jobs scheduled today
completed	Integer	A count of jobs completed today
failed	Integer	A count of jobs failed today

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "active_accounts": 1,
        "delinquent_accounts": 0,
        "all_accounts": 1,
        "invoiced_this_month": null,
        "total_due_balances": null,
        "undeposited_payments": 0,
        "invoices_to_print": 0,
        "open_public_tickets": 0,
        "open_internal_tickets": 0,
        "tickets_by_group": [],
        "ticket_group_names": [],
        "count_of_accounts_status_changed_in_last_30_days": 0,
        "today": {
            "tickets": 0,
            "tickets_closed": 0,
            "payments": "150.00",
            "payments_failed": 2,
            "accounts": 0,
            "debits": null,
            "discounts": null,
            "customers_billed": 0,
            "jobs": {
                "scheduled": 0,
                "completed": 0,
                "failed": 0
            },
            "accounts_activated": 0,
            "bounced_emails": 0,
            "contracts_expiring": 0,
            "towercoverage_submissions_good": 0,
            "towercoverage_submissions_bad": 0
        }
    }
}

System - Get all account groups

Get a list of available account groups.

https://example.sonar.software/api/v1/system/account_groups

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the account group, this can be used when setting an account group on an account
name	String	A descriptive name of the account group

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Habitual Late Payers"
        },
        {
            "id": 2,
            "name": "JC Kenney Employees"
        },
        {
            "id": 3,
            "name": "Free Accounts"
        },
        {
            "id": 4,
            "name": "Employees"
        },
        {
            "id": 5,
            "name": "Friends & Family"
        }
    ],
    "paginator": {
        "total_count": 5,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

System - Get all account statuses

Get a list of available account statuses.

https://example.sonar.software/api/v1/system/account_statuses

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the account status, this can be used when setting the account status on an account
name	String	A descriptive name of the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application
account_super_user_only	Boolean	If this is `true`, only users in a role with the 'Account Super User' permission can set this status on an account

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Lead",
            "active": false,
            "color": "#9b59b6",
            "account_super_user_only": false
        },
        {
            "id": 2,
            "name": "Active",
            "active": true,
            "color": "#123123",
            "account_super_user_only": false
        },
        {
            "id": 3,
            "name": "Inactive",
            "active": false,
            "color": "#fff000",
            "account_super_user_only": false
        },
        {
            "id": 5,
            "name": "My Custom Status Active",
            "active": true
            "color": "#00ff00",
            "account_super_user_only": true
        }
    ],
    "paginator": {
        "total_count": 4,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

System - Get all account statuses

Get a list of available account statuses.

https://example.sonar.software/api/v1/system/account_statuses

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the account status, this can be used when setting the account status on an account
name	String	A descriptive name of the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Lead",
            "active": false,
            "color": "#9b59b6"
        },
        {
            "id": 2,
            "name": "Active",
            "active": true,
            "color": "#123123"
        },
        {
            "id": 3,
            "name": "Inactive",
            "active": false,
            "color": "#fff000"
        },
        {
            "id": 5,
            "name": "My Custom Status Active",
            "active": true
            "color": "#00ff00"
        }
    ],
    "paginator": {
        "total_count": 4,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

System - Get all account types

Get a list of available account types.

https://example.sonar.software/api/v1/system/account_types

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field Type Description

Number

The ID of the account type, this can be used when setting the account type on an account

name

String

A descriptive name of the account type

type

String

The type of account type this is

Allowed values: "residential", "commercial"

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 1,
            "name": "Residential",
            "type": "residential",
        },
        {
            "id": 2,
            "name": "Commercial",
            "type": "commercial",
        },
        {
            "id": 3,
            "name": "Service Trade",
            "type": "commercial",
        }
   ],
   "paginator": {
       "total_count": 6,
       "total_pages": 1,
       "current_page": 1,
       "limit": 100
   }
}

System - Get all address types

Get a list of available address types.

https://example.sonar.software/api/v1/system/address_types

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the address type, this can be used when setting the address type on an address
name	String	A descriptive name of the address type

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Physical"
        },
        {
            "id": 2,
            "name": "Billing"
        },
        {
            "id": 3,
            "name": "Billing"
        },
        {
            "id": 4,
            "name": "Some Other Type"
        }
    ],
    "paginator": {
        "total_count": 4,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

System - Get all custom fields

Get a list of custom fields

https://example.sonar.software/api/v1/system/custom_fields

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the custom field
name	String	The name of the custom field
type	String	The type of field Allowed values: `"text"`, `"checkbox"`, `"select"`, `"date"`
unique	Boolean	Whether input to this custom field must be unique. Only applies to text fields
active	Boolean	If the field is not active, it won't show up on any entities that don't already have a value set
entity_type	String	The type of entity this custom field is displayed on Allowed values: `"account"`
select_options	Array	If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 8,
      "name": "Serial Number for Anti-Virus",
      "type": "text",
      "unique": true,
      "active": true,
      "entity_type": "account",
      "select_options": []
    },
    {
      "id": 7,
      "name": "My First Dropdown",
      "type": "select",
      "unique": false,
      "active": false,
      "entity_type": "account",
      "select_options": [
        {
          "text": "Option Number One"
        },
        {
          "text": "Option Number Two"
        }
      ]
    },
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

System - Get application configuration

Get the current application configuration.

https://example.sonar.software/api/v1/system/application

Success 200

Field	Type	Description
locale	String	The application locale
timezone	String	The application timezone
country	String	An ISO 3166-1 alpha-2 character code representing the country the application is configured for
thousands_separator	String	The character to use to separate thousands (e.g. 1,000 has a comma (,) separator)
decimal_separator	String	The character to use to separate decimals (e.g. 100.34 has a period (.) separator)
date_format	String	The format for dates in the application
currency_symbol	String	The symbol used for currency in the application
time_format	String	The format used for time in the application
units	String	The units used for measurement (metric or imperial)

Success-Response:

HTTP/1.1 200 OK
{
"data": {
"locale": "en",
"timezone": "America/Chicago",
"country": "US",
"thousands_separator": ",",
"decimal_separator": ".",
"date_format": "m/d/Y",
"currency_symbol": "$",
"time_format": "g:i:s",
"units": "metric"
}
}

System - Get individual account group

Get an individual account status.

https://example.sonar.software/api/v1/system/account_groups/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The ID of the account group, this can be used when setting an account group on an account
name	String	A descriptive name of the account group

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Habitual Late Payers"
    }
}

System - Get individual account status

Get an individual account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The ID of the account status, this can be used when setting the account status on an account
name	String	A descriptive name of the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application
account_super_user_only	Boolean	If this is `true`, only users in a role with the 'Account Super User' permission can set this status on an account

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Lead",
        "active": false,
        "color": "#00ff00",
        "account_super_user_only": false
    }
}

System - Get individual account status

Get an individual account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status

Success 200

Field	Type	Description
id	Number	The ID of the account status, this can be used when setting the account status on an account
name	String	A descriptive name of the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Lead",
        "active": false,
        "color": "#00ff00"
    }
}

System - Get individual account type

Get an individual account type.

https://example.sonar.software/api/v1/system/account_types/:id

Parameter

Field	Type	Description
id	Number	The ID of the account type

Success 200

Field Type Description

Number

The ID of the account type, this can be used when setting the account type on an account

name

String

A descriptive name of the account type

type

String

The type of account type this is

Allowed values: "residential", "commercial"

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Residential",
        "type": "residential"
    }
}

System - Get individual address type

Get an individual account address.

https://example.sonar.software/api/v1/system/address_types/:id

Parameter

Field	Type	Description
id	Number	The ID of the address type

Success 200

Field	Type	Description
id	Number	The ID of the address type, this can be used when setting the address type on an address
name	String	A descriptive name of the address type

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Physical"
    }
}

System - Get individual custom field

Get an individual custom field

https://example.sonar.software/api/v1/system/custom_fields/:id

Parameter

Field	Type	Description
id	Number	The id of the custom field

Success 200

Field	Type	Description
id	Number	The internal id of the custom field
name	String	The name of the custom field
type	String	The type of field Allowed values: `"text"`, `"checkbox"`, `"select"`, `"date"`
unique	Boolean	Whether input to this custom field must be unique. Only applies to text fields
active	Boolean	If the field is not active, it won't show up on any entities that don't already have a value set
entity_type	String	The type of entity this custom field is displayed on Allowed values: `"account"`
select_options	Array	If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details

Success-Response:

HTTP/1.1 200 OK
{
  "id": 8,
  "name": "Height of Antenna",
  "type": "text",
  "unique": true,
  "active": true,
  "entity_type": "account",
  "select_options": []
}

System - Update account group

Update an account group.

https://example.sonar.software/api/v1/system/account_groups/:id

Parameter

Field	Type	Description
id	Number	The ID of the account group to update
name	String	A unique name for the account group

Success 200

Field	Type	Description
id	Number	The ID of the account group, this can be used when setting an account group on an account
name	String	A descriptive name of the account group

Success-Response:

 HTTP/1.1 200 OK
 {
    "data": {
        "id": 6,
        "name": "People That I No Longer Like"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update account status

Update an account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status to update
name	String	A unique name for the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application
account_super_user_only	Boolean	If this is `true`, only users in a role with the 'Account Super User' permission can set this status on an account

Success 200

Field	Type	Description
id	Number	The ID of the account status, this can be used when setting the account status on an account
name	String	A descriptive name of the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application
account_super_user_only	Boolean	If this is `true`, only users in a role with the 'Account Super User' permission can set this status on an account

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 5,
       "name": "Pending",
       "active": false,
       "color": "#00ff00",
       "account_super_user_only": true
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update account status

Update an account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field	Type	Description
id	Number	The ID of the account status to update
name	String	A unique name for the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application

Success 200

Field	Type	Description
id	Number	The ID of the account status, this can be used when setting the account status on an account
name	String	A descriptive name of the account status
active	Boolean	Whether or not this status activates customer services
color	String	A 6 digit hex code, prefixed with #, that represents the color for the status in the application

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "id": 5,
       "name": "Pending",
       "active": false,
       "color": "#00ff00"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update account type

Update an account type.

https://example.sonar.software/api/v1/system/account_types/:id

Parameter

Field Type Description

Number

The ID of the account type to update

name

String

A unique name for the account type

type

String

The type of account type this is

Allowed values: "residential", "commercial"

Success 200

Field Type Description

Number

The ID of the account type, this can be used when setting the account type on an account

name

String

A descriptive name of the account type

type

String

The type of status this is

Allowed values: "residential", "commercial"

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
         "id": 12,
         "name": "My Custom Type Updated",
         "type": "commercial"
     }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update address type

Update an address type.

https://example.sonar.software/api/v1/system/address_types/:id

Parameter

Field	Type	Description
id	Number	The ID of the address type to update
name	String	A unique name for the address type

Success 200

Field	Type	Description
id	Number	The ID of the address type, this can be used when setting the address type on an address
name	String	A descriptive name of the address type

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 1,
        "name": "Physical"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update application

Update application

https://example.sonar.software/api/v1/system/application

Parameter

Field	Type	Description
locale optional	String	The application locale. You can retrieve a list of valid locales from /_data/locales
timezone optional	String	The application timezone. You can retrieve a list of valid timezones from /_data/timezones
country optional	String	An ISO 3166-1 alpha-2 character code representing the country the application is configured for. You can retrieve a list of these from /_data/countries
thousands_separator optional	String	The character to use to separate thousands (e.g. 1,000 has a comma (,) separator). Typical options are a space, a comma or a period, although the application allows any characters.
decimal_separator optional	String	The character to use to separate decimals (e.g. 100.34 has a period (.) separator). Typical options are a comma or a period, although the application allows any characters.
date_format optional	String	The format for dates in the application. One of Y-m-d, d/m/Y or m/d/Y. These will format to 2015-01-30, 30/01/2015 and 01/30/2015 respectively.
currency_symbol optional	String	The symbol used for currency in the application. Any characters are allowed.
time_format optional	String	The format used for time in the application, one of g:i:s and H:i:s. These will format to 1:30:34 PM and 13:30:34 respectively. Allowed values: `"g:i:s"`, `"H:i:s"`
units optional	String	The units used for measurement Allowed values: `"metric"`, `"imperial"`

Success 200

Field	Type	Description
locale	String	The application locale
timezone	String	The application timezone
thousands_separator	String	The character to use to separate thousands (e.g. 1,000 has a comma (,) separator)
decimal_separator	String	The character to use to separate decimals (e.g. 100.34 has a period (.) separator)
date_format	String	The format for dates in the application
currency_symbol	String	The symbol used for currency in the application
time_format	String	The format used for time in the application
units	String	The units used for measurement (metric or imperial)

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
       "locale": "en",
        "timezone": "America/Chicago",
        "country": "US",
        "thousands_separator": ",",
        "decimal_separator": ".",
        "date_format": "m/d/Y",
        "currency_symbol": "$",
        "time_format": "g:i:s",
        "units": "metric"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
            "message": {
            "locale": "The selected language is invalid."
         },
         "status_code": 422
     }
 }

System - Update custom field

Update a custom field. The type and entity_type cannot be changed once created

https://example.sonar.software/api/v1/system/custom_fields/:id

Parameter

Field	Type	Description
id	Number	The ID of the custom field
name	String	The name of the custom field
unique	Boolean	Whether input to this custom field must be unique. Only applies to text fields and should not be submitted for other types
active	Boolean	If the field is not active, it won't show up on any entities that don't already have a value set
select_options	Array	If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details. This field should not be submitted for other types

Success 200

Field	Type	Description
id	Number	The internal id of the custom field
name	String	The name of the custom field
type	String	The type of field Allowed values: `"text"`, `"checkbox"`, `"select"`
unique	Boolean	Whether input to this custom field must be unique. Only applies to text fields
active	Boolean	If the field is not active, it won't show up on any accounts that don't already have a value set
entity_type	String	The type of entity this custom field is displayed on Allowed values: `"account"`
select_options	Array	If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details

Success-Response:

HTTP/1.1 200 OK
{
  "id": 8,
  "name": "Height of Antenna",
  "type": "text",
  "unique": true,
  "active": true,
  "entity_type": "account",
  "select_options": []
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique": "Unique must be a boolean."
         },
         "status_code": 422
     }
 }

Task Templates

Task_Templates - Create a new task template

Create a new task template.

https://example.sonar.software/api/v1/system/misc/task_templates

Parameter

Field	Type	Description
name	String	A name for the task template

Success 200

Field	Type	Description
id	Number	The ID of the task template.
name	String	The name of the task template

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Some test name",
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Task_Templates - Create a new template task.

Create a new template task. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks

Parameter

Field	Type	Description
name	String	A name for the template task

Success 200

Field	Type	Description
id	Number	The ID of the task template.
task	String	The name of the task

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "task": "Wash the dishes",
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Task_Templates - Delete a task template

Delete a task template

https://example.sonar.software/api/v1/system/misc/task_templates/:id

Parameter

Field	Type	Description
id	Number	The ID of the task template

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the task template could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "task template does not exist.",
         "status_code": 404
     }
 }

Task_Templates - Delete a template task.

Delete a template task. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks/:template_task_id

Parameter

Field	Type	Description
id	Number	The ID of the task template
template_task_id	Number	The ID of the template task

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the template task could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "template task does not exist.",
         "status_code": 404
     }
 }

Task_Templates - Get all task templates

Get all task templates

https://example.sonar.software/api/v1/system/misc/task_templates

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the task template.
name	String	The name of the task template

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Installation tasks"
    },
    {
      "id": 1,
      "name": "Service call tasks"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Task_Templates - Get all template tasks.

Get all template tasks. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the task template.
task	String	The name of the task

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 7,
      "task": "Do something"
    },
    {
      "id": 6,
      "task": "test"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Task_Templates - Get an individual task template

Get an individual task template

https://example.sonar.software/api/v1/system/misc/task_templates/:id

Parameter

Field	Type	Description
id	Number	The ID of the task template

Success 200

Field	Type	Description
id	Number	The ID of the task template.
name	String	The name of the task template

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Some random tasks"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Task_Templates - Get an individual template task.

Get an individual template task. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks/:template_task_id

Parameter

Field	Type	Description
id	Number	The ID of the task template
template_task_id	Number	The ID of the template task

Success 200

Field	Type	Description
id	Number	The ID of the template task.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "task": "Do something"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Task_Templates - Update task template

Update an existing task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id

Parameter

Field	Type	Description
id	Number	The task template ID
name optional	String	The name of the task template

Success 200

Field	Type	Description
id	Number	The ID of the task template.
name	String	The name of the task template

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "A bunch of tasks"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Task_Templates - Update template task.

Update an existing template task. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks/:task_template_id

Parameter

Field	Type	Description
id	Number	The task template ID
template_task_id	Number	The template task ID

Success 200

Field	Type	Description
id	Number	The ID of the template task.
task	String	The task

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "task": "Jump rope"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tasks

Tasks - Attach a task to an entity

Attach a task to an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks

Parameter

Field	Type	Description
id	Number	The ID of the entity
entity	String	The entity to attach to. Allowed values: `"tickets"`, `"accounts"`, `"network_sites"`, `"jobs"`
description	String	A description of the task
user_id optional	Number	The ID of a user you want to assign this task to
due_date optional	Date	The date the task is due

Success 200

Field	Type	Description
id	Number	The ID of the task
description	String	The description of the task
user_id	Number	The ID of the user assigned to the task
due_date	Date	The date the task is due
complete	Boolean	Whether or not the task has been completed
completed_by	String	The user ID of the person who completed the task, if it has been completed
completed_at	DateTime	The date and time in UTC that the task was completed, if it has been completed

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "description": "Build a space elevator.",
    "user_id": 2,
    "due_date": "2016-01-02",
    "complete": false,
    "completed_by": null,
    "completed_at": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "id": "The ID must be an integer."
     },
     "status_code": 422
   }
 }

Tasks - Attach a task to an entity

Attach a task to an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks

Parameter

Field	Type	Description
id	Number	The ID of the entity
entity	String	The entity to attach to. Allowed values: `"tickets"`, `"accounts"`, `"network_sites"`
description	String	A description of the task
user_id optional	Number	The ID of a user you want to assign this task to
due_date optional	Date	The date the task is due

Success 200

Field	Type	Description
id	Number	The ID of the task
description	String	The description of the task
user_id	Number	The ID of the user assigned to the task
due_date	Date	The date the task is due
complete	Boolean	Whether or not the task has been completed
completed_by	String	The user ID of the person who completed the task, if it has been completed
completed_at	DateTime	The date and time in UTC that the task was completed, if it has been completed

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "description": "Build a space elevator.",
    "user_id": 2,
    "due_date": "2016-01-02",
    "complete": false,
    "completed_by": null,
    "completed_at": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "id": "The ID must be an integer."
     },
     "status_code": 422
   }
 }

Tasks - Delete a task

Delete a task from an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description

Number

The ID of the entity

entity

String

The entity

Allowed values: "tickets", "accounts", "network_sites", "jobs"

task_id

Number

The ID of the task

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the task could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Task does not exist.",
         "status_code": 404
     }
 }

Tasks - Delete a task

Delete a task from an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description

Number

The ID of the entity

entity

String

The entity

Allowed values: "tickets", "accounts", "network_sites"

task_id

Number

The ID of the task

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the task could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Task does not exist.",
         "status_code": 404
     }
 }

Tasks - Get all tasks on an entity

Get all tasks on an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the entity
entity	String	The entity Allowed values: `"tickets"`, `"accounts"`, `"network_sites"`, `"jobs"`

Success 200

Field	Type	Description
id	Number	The ID of the task
description	String	The description of the task
user_id	Number	The ID of the user assigned to the task
due_date	Date	The date the task is due
complete	Boolean	Whether or not the task has been completed
completed_by	String	The user ID of the person who completed the task, if it has been completed
completed_at	DateTime	The date and time in UTC that the task was completed, if it has been completed

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "description": "Here's a description of what I want you to do.",
      "user_id": 1,
      "due_date": "2016-05-03",
      "complete": false,
      "completed_by": null,
      "completed_at": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tasks - Get all tasks on an entity

Get all tasks on an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return
id	Number	The ID of the entity
entity	String	The entity Allowed values: `"tickets"`

Success 200

Field	Type	Description
id	Number	The ID of the task
description	String	The description of the task
user_id	Number	The ID of the user assigned to the task
due_date	Date	The date the task is due
complete	Boolean	Whether or not the task has been completed
completed_by	String	The user ID of the person who completed the task, if it has been completed
completed_at	DateTime	The date and time in UTC that the task was completed, if it has been completed

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "description": "Here's a description of what I want you to do.",
      "user_id": 1,
      "due_date": "2016-05-03",
      "complete": false,
      "completed_by": null,
      "completed_at": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tasks - Get an individual task

Get an individual task.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description

Number

The ID of the entity

entity

String

The entity

Allowed values: "tickets", "accounts", "network_sites", "jobs"

task_id

Number

The ID of the task

Success 200

Field	Type	Description
id	Number	The ID of the task
description	String	The description of the task
user_id	Number	The ID of the user assigned to the task
due_date	Date	The date the task is due
complete	Boolean	Whether or not the task has been completed
completed_by	String	The user ID of the person who completed the task, if it has been completed
completed_at	DateTime	The date and time in UTC that the task was completed, if it has been completed

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "description": "Here's a description of what I want you to do.",
    "user_id": 1,
    "due_date": "2016-05-03",
    "complete": false,
    "completed_by": null,
    "completed_at": null
  }
}

Tasks - Get an individual task

Get an individual task.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description

Number

The ID of the entity

entity

String

The entity

Allowed values: "tickets"

task_id

Number

The ID of the task

Success 200

Field	Type	Description
id	Number	The ID of the task
description	String	The description of the task
user_id	Number	The ID of the user assigned to the task
due_date	Date	The date the task is due
complete	Boolean	Whether or not the task has been completed
completed_by	String	The user ID of the person who completed the task, if it has been completed
completed_at	DateTime	The date and time in UTC that the task was completed, if it has been completed

Success-Response:

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "description": "Here's a description of what I want you to do.",
    "user_id": 1,
    "due_date": "2016-05-03",
    "complete": false,
    "completed_by": null,
    "completed_at": null
  }
}

Tasks - Update a task

Update an existing task.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field	Type	Description
id	Number	The ID of the entity
entity	String	The entity Allowed values: `"tickets"`, `"accounts"`, `"network_sites"`, `"jobs"`
task_id	Number	The ID of the task
description optional	String	A description of the task
user_id optional	Number	The ID of a user you want to assign this task to
due_date optional	Date	The date the task is due
complete optional	Boolean	Set to true if the task is complete, or false if not.

Success 200

Field	Type	Description
id	Number	The ID of the task
description	String	The description of the task
user_id	Number	The ID of the user assigned to the task
due_date	Date	The date the task is due
complete	Boolean	Whether or not the task has been completed
completed_by	String	The user ID of the person who completed the task, if it has been completed
completed_at	DateTime	The date and time in UTC that the task was completed, if it has been completed

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "description": "Here's a description of what I want you to do.",
    
    "user_id": 1,
    "due_date": "2016-05-03",
    "complete": true,
    "completed_by": 1,
    "completed_at": "2016-05-02 23:59:59"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "id": "The ID must be an integer."
     },
     "status_code": 422
   }
 }

Tasks - Update a task

Update an existing task.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field	Type	Description
id	Number	The ID of the entity
entity	String	The entity Allowed values: `"tickets"`, `"accounts"`, `"network_sites"`
task_id	Number	The ID of the task
description optional	String	A description of the task
user_id optional	Number	The ID of a user you want to assign this task to
due_date optional	Date	The date the task is due
complete optional	Boolean	Set to true if the task is complete, or false if not.

Success 200

Field	Type	Description
id	Number	The ID of the task
description	String	The description of the task
user_id	Number	The ID of the user assigned to the task
due_date	Date	The date the task is due
complete	Boolean	Whether or not the task has been completed
completed_by	String	The user ID of the person who completed the task, if it has been completed
completed_at	DateTime	The date and time in UTC that the task was completed, if it has been completed

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "description": "Here's a description of what I want you to do.",
    
    "user_id": 1,
    "due_date": "2016-05-03",
    "complete": true,
    "completed_by": 1,
    "completed_at": "2016-05-02 23:59:59"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "id": "The ID must be an integer."
     },
     "status_code": 422
   }
 }

Ticket Categories

Ticket_Categories - Create a new ticket category

Create a new ticket category.

https://example.sonar.software/api/v1/system/tickets/ticket_categories

Parameter

Field	Type	Description
name	String	A name for the ticket category

Success 200

Field	Type	Description
id	Number	The ID of the ticket category.
name	String	The name of the ticket category.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "The porridge was too hot"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name is already in use."
     },
     "status_code": 422
   }
 }

Ticket_Categories - Delete ticket category

Delete a ticket category.

https://example.sonar.software/api/v1/system/tickets/ticket_categories/:id

Parameter

Field	Type	Description
id	Number	The ID of the ticket category

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the ticket category could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Ticket category does not exist.",
         "status_code": 404
     }
 }

Ticket_Categories - Get all ticket categories

Get all ticket categories

https://example.sonar.software/api/v1/system/tickets/ticket_categories

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the ticket category.
name	String	The name of the ticket category.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
    "id": 2,
    "name": "The porridge was too hot"
   },
   {
    "id": 3,
    "name": "The porridge was too cold"
   }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Ticket_Categories - Get an individual ticket category

Get an individual ticket category

https://example.sonar.software/api/v1/system/tickets/ticket_categories/:id

Parameter

Field	Type	Description
id	Number	The ID of the ticket category

Success 200

Field	Type	Description
id	Number	The ID of the ticket category.
name	String	The name of the ticket category.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "The porridge was too hot"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Ticket_Categories - Update ticket category

Update an existing ticket category.

https://example.sonar.software/api/v1/system/tickets/ticket_categories/:id

Parameter

Field	Type	Description
id	Number	The ID of the ticket category.
name optional	String	The name of the ticket category.

Success 200

Field	Type	Description
id	Number	The ID of the ticket category.
name	String	The name of the ticket category.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "The porridge was too hot"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Ticket Groups

Ticket_Groups - Create a new ticket group

Create a new ticket group.

https://example.sonar.software/api/v1/system/tickets/ticket_groups

Parameter

Field	Type	Description
name	String	A name for the ticket group
private optional	Boolean	Whether the group is private Default value: `false`
enabled optional	Boolean	Whether the group is enabled Default value: `true`
users optional	Array	An array of user IDs that are associated with the group

Success 200

Field	Type	Description
id	Number	The ID of the ticket group.
name	String	The name of the ticket group
private	Boolean	Whether the group is private
enabled	Boolean	Whether the group is enabled
users	Array	An array of user IDs that are associated with the group

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Some test name",
    "private": false,
    "enabled": true,
    "users": [
       1,
       2
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name is already taken."
     },
     "status_code": 422
   }
 }

Ticket_Groups - Delete ticket group

Delete a ticket group.

https://example.sonar.software/api/v1/system/tickets/ticket_groups/:id

Parameter

Field	Type	Description
id	Number	The ID of the ticket group

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the ticket group could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Ticket group does not exist.",
         "status_code": 404
     }
 }

Ticket_Groups - Get all ticket groups

Get all tickets

https://example.sonar.software/api/v1/system/tickets/ticket_groups

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the ticket group.
name	String	The name of the ticket group
private	Boolean	Whether the group is private
enabled	Boolean	Whether the group is enabled
users	Array	An array of user IDs that are associated with the group

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
     "id": 1,
     "name": "Test",
     "private": false,
     "enabled": true,
     "users": []
   },
   {
     "id": 4,
     "name": "Test yet again",
     "private": false,
     "enabled": true,
     "users": [
       1
     ]
   }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Ticket_Groups - Get an individual ticket group

Get an individual ticket group

https://example.sonar.software/api/v1/system/tickets/ticket_groups/:id

Parameter

Field	Type	Description
id	Number	The ID of the ticket group

Success 200

Field	Type	Description
id	Number	The ID of the ticket group.
name	String	The name of the ticket group
private	Boolean	Whether the group is private
enabled	Boolean	Whether the group is enabled
users	Array	An array of user IDs that are associated with the group

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
     "id": 1,
     "name": "Test",
     "private": false,
     "enabled": true,
     "users": []
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Ticket_Groups - Update ticket group

Update an existing ticket group.

https://example.sonar.software/api/v1/system/tickets/ticket_groups/:id

Parameter

Field	Type	Description
name optional	String	A name for the ticket group
private optional	Boolean	Whether the group is private Default value: `false`
enabled optional	Boolean	Whether the group is enabled Default value: `true`
users optional	Array	An array of user IDs that are associated with the group

Success 200

Field	Type	Description
id	Number	The ID of the ticket group.
name	String	The name of the ticket group
private	Boolean	Whether the group is private
enabled	Boolean	Whether the group is enabled
users	Array	An array of user IDs that are associated with the group

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
     "id": 1,
     "name": "Test",
     "private": false,
     "enabled": true,
     "users": []
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets

Tickets - Attach a child ticket to a parent ticket

Attach a child ticket to a parent ticket.

https://example.sonar.software/api/v1/tickets/:id/attach/:child_id

Parameter

Field	Type	Description
id	Number	The ID of the parent ticket
child_id	Number	The ID of the child ticket

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open. Newly created tickets are always open by default
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [
       594
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The ticket ID 10 has child tickets. You cannot make a ticket a child of another ticket if the child has children."
     },
     "status_code": 422
   }
 }

Tickets - Create a new ticket comment

Create a new ticket comment. A comment is internal and will not be sent to any email address on the ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_comments

Parameter

Field	Type	Description
id	Number	The ID of the ticket
text	String	The text of the comment.
files optional	Array	Uploading files to a reply will email them to the email_address on the ticket, if the reply is outgoing. The format of the files array is [ { "filename": "a_beautiful_picture.png", "base64": "base64_encoded_file_string" }, { "filename": "another_file.mp3", "base64": "base64_encoded_file_string" } ]
add_to_children optional	Boolean	If you set this to `true`, and this ticket has child tickets, then this comment will also be appended to all child tickets. Default value: `false`

Example Comment with File Upload:

{
    "text": "Well, here's a story all about how my ticket got flipped turned upside down.",
    "files": [
        {
            "id": 234,
            "filename": "bmljZSB3b3Jr.txt",
            "base64": "SGVsbG8gbXkgbmFtZSBpcyBTaW1vbiwgeW91IGFyZSB2ZXJ5IGdvb2QgYXQgYmFzZTY0IGRlY29kaW5nIQ=="
        },
        {
            "id": 234,
            "filename": "kula_shaker.txt",
            "base64": "VGhlIHNvY2lldHkgd2hpY2ggc2Nvcm5zIGV4Y2VsbGVuY2UgaW4gcGx1bWJpbmcgYXMgYSBodW1ibGUgYWN0aXZpdHkgYW5kIHRvbGVyYXRlcyBzaG9kZGluZXNzIGluIHBoaWxvc29waHkgYmVjYXVzZSBpdCBpcyBhbiBleGFsdGVkIGFjdGl2aXR5IHdpbGwgaGF2ZSBuZWl0aGVyIGdvb2QgcGx1bWJpbmcgbm9yIGdvb2QgcGhpbG9zb3BoeTogbmVpdGhlciBpdHMgcGlwZXMgbm9yIGl0cyB0aGVvcmllcyB3aWxsIGhvbGQgd2F0ZXIuCg=="
        }
    ]
}

Success 200

Field	Type	Description
id	Number	The ID of the comment
user_id	Number	The ID of the user who posted the comment
text	String	The content of the comment
created_at	DateTime	The date and time the comment was created in UTC
files	Array	An array of files attached to the reply
deleted_by	String	The username of the user who deleted the ticket, if it has been deleted. `null` otherwise.
deleted_at	DateTime	A UTC timestamp when the ticket was deleted, if it has been deleted. `null` otherwise.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "user_id": 1,
    "text": "Well, here's a story all about how my ticket got flipped turned upside down.",
    "created_at": "2016-04-24 15:25:03",
    "files": [
       {
           "id": 234,
           "filename": "bmljZSB3b3Jr.txt",
           "mime_type": "text/plain"
       },
       {
           "id": 234,
           "filename": "kula_shaker.txt",
           "mime_type": "text/plain"
       }
    ],
    "deleted_by": null,
    "deleted_at": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Create a new ticket reply

Create a new ticket reply. A reply is public and will be sent to the email address set on the ticket. Replies can only be added to public tickets. Basic HTML can be used.

https://example.sonar.software/api/v1/tickets/:id/ticket_replies

Parameter

Field	Type	Description
id	Number	The ID of the ticket
text	String	The text of the reply.
incoming optional	Boolean	Whether or not the reply is incoming. If this is true, the reply will be treated as though it was received from a customer. If this is false, the reply will be treated as though posted by an employee, and will be emailed to the customer. Default value: `false`
author optional	String	Required if incoming is true. This is a name for the author of the reply.
author_email optional	String	Required if incoming is true. This is the email address of the author of the reply.
files optional	Array	Uploading files to a reply will email them to the email_address on the ticket. The format of the files array is [ { "filename": "a_beautiful_picture.png", "base64": "base64_encoded_file_string" }, { "filename": "another_file.mp3", "base64": "base64_encoded_file_string" } ]
add_to_children optional	Boolean	If you set this to `true`, and this ticket has child tickets, then this reply will also be appended to all public child tickets. If the reply fails to apply to a child ticket for any reason (for example, the child ticket has an invalid inbound email account associated with it) then the child reply will be discarded silently for that specific child ticket. If you set this to true, you will be able to submit a reply on an internal ticket, as long as the ticket has children. In this case, the data response will be an array of successful replies. Default value: `false`

Example Reply with File Upload:

{
    "text": "I am a dancing master!",
    "files": [
        {
            "id": 234,
            "filename": "bmljZSB3b3Jr.txt",
            "base64": "SGVsbG8gbXkgbmFtZSBpcyBTaW1vbiwgeW91IGFyZSB2ZXJ5IGdvb2QgYXQgYmFzZTY0IGRlY29kaW5nIQ=="
        },
        {
            "id": 234,
            "filename": "kula_shaker.txt",
            "base64": "VGhlIHNvY2lldHkgd2hpY2ggc2Nvcm5zIGV4Y2VsbGVuY2UgaW4gcGx1bWJpbmcgYXMgYSBodW1ibGUgYWN0aXZpdHkgYW5kIHRvbGVyYXRlcyBzaG9kZGluZXNzIGluIHBoaWxvc29waHkgYmVjYXVzZSBpdCBpcyBhbiBleGFsdGVkIGFjdGl2aXR5IHdpbGwgaGF2ZSBuZWl0aGVyIGdvb2QgcGx1bWJpbmcgbm9yIGdvb2QgcGhpbG9zb3BoeTogbmVpdGhlciBpdHMgcGlwZXMgbm9yIGl0cyB0aGVvcmllcyB3aWxsIGhvbGQgd2F0ZXIuCg=="
        }
    ]
}

Success 200

Field	Type	Description
id	Number	The ID of the reply
user_id	Number	The ID of the user who posted the reply
text	String	The content of the reply
author	String	The name of the user/person who posted the reply
author_email	String	The email address of the user/person who posted the reply
created_at	DateTime	The date and time the reply was created in UTC
files	Array	An array of files attached to the reply
incoming	Boolean	Whether or not the reply was incoming or outgoing

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "user_id": 1,
    "text": "I am a dancing master!",
    "author": "Hulk Hogan",
    "author_email": "hulkamania@example.org",
    "created_at": "2016-04-26 14:22:03",
    "files": [
       {
           "id": 234,
           "filename": "bmljZSB3b3Jr.txt",
           "mime_type": "text/plain"
       },
       {
           "id": 234,
           "filename": "kula_shaker.txt",
           "mime_type": "text/plain"
       }
    ],
    "incoming": false,
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Create a new ticket

Create a new ticket.

https://example.sonar.software/api/v1/tickets

Parameter

Field	Type	Description
subject	String	A subject for the ticket
type	String	The type of ticket. Internal is for internal use only. Public will send emails to a customer if a reply is posted. Allowed values: `"public"`, `"internal"`
inbound_email_account_id optional	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, ignored if the ticket is internal.
ticket_group_id optional	Number	A valid ID for a ticket group. A ticket must have at least a group or a responsible user.
category_ids optional	Array	An array of ticket category IDs to assign to this ticket.
user_id optional	Number	A valid responsible user ID. A ticket must have at least a group or a responsible user.
assignee optional	String	The type of entity to assign the ticket to. Public tickets can only be assigned to accounts. Allowed values: `"accounts"`
assignee_id optional	Number	The ID of the assignee to assign this ticket to.
due_date optional	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address optional	String	An email address, required if this is a public ticket.
priority optional	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Default value: `4` Allowed values: `1`, `2`, `3`, `4`
comment optional	String	The first comment for the ticket. A comment is internal only and will not be sent to a customer. A ticket must have at least one comment or reply to open it.
reply optional	String	The first reply for the ticket. A reply is public and will be sent to the email address on the ticket. A reply can only be saved if the ticket has an email address.
comment_files optional	Array	An array of files to attach to the comment. The format of the files array is [ { "filename": "a_beautiful_picture.png", "base64": "base64_encoded_file_string" }, { "filename": "another_file.mp3", "base64": "base64_encoded_file_string" } ].
reply_files optional	Array	Uploading files to a reply will email them to the email_address on the ticket. The format of the files array is [ { "filename": "a_beautiful_picture.png", "base64": "base64_encoded_file_string" }, { "filename": "another_file.mp3", "base64": "base64_encoded_file_string" } ].

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open. Newly created tickets are always open by default
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply. Will always be false if the ticket is internal.
closed_at	Date	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Create a new ticket

Create a new ticket.

https://example.sonar.software/api/v1/tickets

Parameter

Field	Type	Description
subject	String	A subject for the ticket
type	String	The type of ticket. Internal is for internal use only. Public will send emails to a customer if a reply is posted. You can only create a public ticket on an account. Allowed values: `"public"`, `"internal"`
inbound_email_account_id optional	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, ignored if the ticket is internal.
ticket_group_id optional	Number	A valid ID for a ticket group. A ticket must have at least a group or a responsible user.
category_ids optional	Array	An array of ticket category IDs to assign to this ticket.
user_id optional	Number	A valid responsible user ID. A ticket must have at least a group or a responsible user.
assignee optional	String	The type of entity to assign the ticket to. Public tickets can only be assigned to accounts. Allowed values: `"accounts"`, `"network_sites"`
assignee_id optional	Number	The ID of the assignee to assign this ticket to.
due_date optional	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address optional	String	An email address, required if this is a public ticket.
priority optional	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Default value: `4` Allowed values: `1`, `2`, `3`, `4`
comment optional	String	The first comment for the ticket. A comment is internal only and will not be sent to a customer. A ticket must have at least one comment or reply to open it.
reply optional	String	The first reply for the ticket. A reply is public and will be sent to the email address on the ticket. A reply can only be saved if the ticket has an email address.

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`, `"network_sites"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open. Newly created tickets are always open by default
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply. Will always be false if the ticket is internal.
closed_at	Date	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Create a new ticket

Create a new ticket.

https://example.sonar.software/api/v1/tickets

Parameter

Field	Type	Description
subject	String	A subject for the ticket
type	String	The type of ticket. Internal is for internal use only. Public will send emails to a customer if a reply is posted. Allowed values: `"public"`, `"internal"`
inbound_email_account_id optional	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, ignored if the ticket is internal.
ticket_group_id optional	Number	A valid ID for a ticket group. A ticket must have at least a group or a responsible user.
category_ids optional	Array	An array of ticket category IDs to assign to this ticket.
user_id optional	Number	A valid responsible user ID. A ticket must have at least a group or a responsible user.
assignee optional	String	The type of entity to assign the ticket to. Public tickets can only be assigned to accounts. Allowed values: `"accounts"`
assignee_id optional	Number	The ID of the assignee to assign this ticket to.
due_date optional	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address optional	String	An email address, required if this is a public ticket.
priority optional	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Default value: `4` Allowed values: `1`, `2`, `3`, `4`
comment optional	String	The first comment for the ticket. A comment is internal only and will not be sent to a customer. A ticket must have at least one comment or reply to open it.
reply optional	String	The first reply for the ticket. A reply is public and will be sent to the email address on the ticket. A reply can only be saved if the ticket has an email address.

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open. Newly created tickets are always open by default
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply. Will always be false if the ticket is internal.
closed_at	Date	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Delete a ticket

Delete a ticket. This will remove all tasks, files, and other attached items as well.

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field	Type	Description
id	Number	The ID of the ticket
task_id	Number	The ID of the task

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the ticket could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Ticket does not exist.",
         "status_code": 404
     }
 }

Tickets - Delete ticket comment

Delete a ticket comment. You can only delete your own comments, unless you are a ticket super user. This will set deleted_at and deleted_by on the comment, and remove the comment text.

https://example.sonar.software/api/v1/tickets/:ticket_id/ticket_comments/:comment_id

Parameter

Field	Type	Description
ticket_id	Number	The ID of the ticket
comment_id	Number	The ID of the comment

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the comment could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Comment does not exist.",
         "status_code": 404
     }
 }

Tickets - Detach a child ticket from a parent ticket

Detach a child ticket from a parent ticket.

https://example.sonar.software/api/v1/tickets/:id/detach/:child_id

Parameter

Field	Type	Description
id	Number	The ID of the parent ticket
child_id	Number	The ID of the child ticket

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open. Newly created tickets are always open by default
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": []
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The ticket ID 12 is not a child of ticket ID 43."
     },
     "status_code": 422
   }
 }

Tickets - Get a list of subscribed tickets

Get a list of the ticket IDs you are currently subscribed to.

https://example.sonar.software/api/v1/tickets/subscribed

Success 200

Field	Type	Description
ticket_ids	Array	Array of ticket IDs.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "ticket_ids": []
  }
}

Tickets - Get all comments on a ticket

Get a list of comments for a ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_comments

Parameter

Field	Type	Description
id	Number	The ID of the ticket
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the reply
user_id	Number	The ID of the user who posted the comment.
text	String	The content of the comment
created_at	DateTime	The date and time the reply was created in UTC
files	Array	An array of files attached to the reply
deleted_by	String	The username of the user who deleted the ticket, if it has been deleted. `null` otherwise.
deleted_at	DateTime	A UTC timestamp when the ticket was deleted, if it has been deleted. `null` otherwise.

Success-Response:

 HTTP/1.1 201 OK
 {
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "text": "There is a big problem here, the pedestal is full of snakes!",
      "created_at": "2016-04-21 22:00:55",
      "files": [],
      "deleted_by": null,
      "deleted_at": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tickets - Get all replies on a ticket

Get a list of replies for a ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_replies

Parameter

Field	Type	Description
id	Number	The ID of the ticket
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the reply
user_id	Number	The ID of the user who posted the reply. This will be null if the reply was received from an external source (e.g. inbound email.)
text	String	The content of the reply
author	String	The name of the user/person who posted the reply
author_email	String	The email address of the user/person who posted the reply
created_at	DateTime	The date and time the reply was created in UTC
files	Array	An array of files attached to the reply
incoming	Boolean	Whether or not the reply was incoming or outgoing

Success-Response:

HTTP/1.1 201 OK
{
  "data": [
    {
      "id": 66,
      "user_id": null,
      "text": "Some test reply",
      "author": "Simon Westlake",
      "author_email": "simon@sonar.software",
      "created_at": "2016-05-03 15:15:03",
      "files": [
        {
          "id": 19,
          "filename": "Invoice for March 2016.odt",
          "mime_type": "application/vnd.oasis.opendocument.text"
        },
        {
          "id": 18,
          "filename": "Invoice for July 2015.pdf",
          "mime_type": "application/pdf"
        }
      ]
    },
    "incoming": false
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Get all tickets for an entity

Get all tickets for a specific entity (e.g. an account

https://example.sonar.software/api/v1/:entity/:entity_id/tickets

Parameter

Field	Type	Description
entity	String	The entity to get tickets for (e.g. accounts)
entity_id	Number	The ID of the entity to get tickets for
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "subject": "The porridge was too hot",
      "type": "internal",
      "ticket_group_id": null,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": null,
      "email_address": null,
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": true,
       "parent_ticket_id": 1,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tickets - Get all tickets

Get all tickets

https://example.sonar.software/api/v1/tickets

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`, `"network_sites"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply
closed_at	DateTime	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "subject": "The porridge was too hot",
      "type": "internal",
      "ticket_group_id": null,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": null,
      "email_address": null,
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": true,
       "parent_ticket_id": 1,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false,
       "last_reply_incoming": false,
        "closed_at": null,
        "closed_by_user_id": null,
        "created_at": "2016-05-20 14:19:35"
    },
    {
      "id": 1,
      "subject": "The porridge was too cold",
      "type": "internal",
      "ticket_group_id": 1,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": '2016-04-02',
      "email_address": 'goldilocks@sonar.software',
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": false,
       "parent_ticket_id": null,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false,
       "last_reply_incoming": false,
        "closed_at": null,
        "closed_by_user_id": null,
        "created_at": "2016-05-20 14:19:35"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tickets - Get all tickets

Get all tickets

https://example.sonar.software/api/v1/tickets

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply
closed_at	DateTime	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "subject": "The porridge was too hot",
      "type": "internal",
      "ticket_group_id": null,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": null,
      "email_address": null,
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": true,
       "parent_ticket_id": 1,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false,
       "last_reply_incoming": false,
        "closed_at": null,
        "closed_by_user_id": null,
        "created_at": "2016-05-20 14:19:35"
    },
    {
      "id": 1,
      "subject": "The porridge was too cold",
      "type": "internal",
      "ticket_group_id": 1,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": '2016-04-02',
      "email_address": 'goldilocks@sonar.software',
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": false,
       "parent_ticket_id": null,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false,
       "last_reply_incoming": false,
        "closed_at": null,
        "closed_by_user_id": null,
        "created_at": "2016-05-20 14:19:35"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tickets - Get an individual ticket reply

Get a specific reply on a ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_replies/:reply_id

Parameter

Field	Type	Description
id	Number	The ID of the ticket
reply_id	Number	The ID of the reply

Success 200

Field	Type	Description
id	Number	The ID of the reply
user_id	Number	The ID of the user who posted the reply. This will be null if the reply was received from an external source (e.g. inbound email.)
text	String	The content of the reply
author	String	The name of the user/person who posted the reply
author_email	String	The email address of the user/person who posted the reply
created_at	DateTime	The date and time the reply was created in UTC
files	Array	An array of files attached to the reply
incoming	Boolean	Whether or not the reply was incoming or outgoing

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 66,
    "user_id": null,
    "author": "Simon Westlake",
    "author_email": "simon@sonar.software",
    "text": "Writing ticket replies is so easy, a caveman could do it!",
    "created_at": "2016-05-03 15:15:03",
    "files": [
      {
        "id": 19,
        "filename": "Invoice for March 2016.odt",
        "mime_type": "application/vnd.oasis.opendocument.text"
      },
      {
        "id": 18,
        "filename": "Invoice for July 2015.pdf",
        "mime_type": "application/pdf"
      }
    ]
  },
  "incoming": false
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Get individual ticket comment

Get a a specific comment on a ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_comments/:comment_id

Parameter

Field	Type	Description
id	Number	The ID of the ticket
comment_id	Number	The ID of the comment

Success 200

Field	Type	Description
id	Number	The ID of the reply
user_id	Number	The ID of the user who posted the comment.
text	String	The content of the comment
created_at	DateTime	The date and time the reply was created in UTC
files	Array	An array of files attached to the reply
deleted_by	String	The username of the user who deleted the ticket, if it has been deleted. `null` otherwise.
deleted_at	DateTime	A UTC timestamp when the ticket was deleted, if it has been deleted. `null` otherwise.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "user_id": 1,
    "text": "I just wanted to say how nice this ticket is.",
    "created_at": "2016-04-21 22:00:55",
    "files": [],
    "deleted_by": null,
    "deleted_at": null
  }
}

Tickets - Get individual ticket

Get an individual ticket

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field	Type	Description
id	Number	The ID of the ticket

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`, `"network_sites"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply
closed_at	DateTime	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [
       5,
       7
    ],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Get individual ticket

Get an individual ticket

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field	Type	Description
id	Number	The ID of the ticket

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
child_ticket_ids	Array	An array of child ticket IDs of this ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply
closed_at	DateTime	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [
       5,
       7
    ],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Merge two tickets

Merge one ticket into another. The ticket referenced as :id will be kept, and the ticket merging into :id will be deleted. When merging one ticket into another, the ticket referenced as :id will gain all the replies and comments on the ticket referenced in child_ticket_id, and the child_ticket_id ticket will be deleted.

https://example.sonar.software/api/v1/tickets/:id/merge

Parameter

Field	Type	Description
id	Number	The ID of the master ticket
child_ticket_id	Number	The ID of the ticket to merge in.
success	Boolean	Will be true if the merge succeeds.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "You cannot merge a ticket into itself.",
     "status_code": 422
   }
 }

Tickets - Subscribe to a ticket

Subscribe to a ticket. This will add it to your list of subscribed tickets.

https://example.sonar.software/api/v1/tickets/:id/subscribe

Parameter

Field	Type	Description
id	Number	The ID of the ticket

Success 200

Field	Type	Description
success	Boolean	Will be true if subscription succeeded

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Unsubscribe from a ticket

Unsubscribe from a ticket. This will remove it from your list of subscribed tickets.

https://example.sonar.software/api/v1/tickets/:id/unsubscribe

Parameter

Field	Type	Description
id	Number	The ID of the ticket

Success 200

Field	Type	Description
success	Boolean	Will be true if unsubscription succeeded

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Update ticket comment

Update an existing ticket comment. You can only update your own comments, unless you are a ticket super user.

https://example.sonar.software/api/v1/tickets/:id/ticket_comments/:comment_id

Parameter

Field	Type	Description
id	Number	The ticket ID
comment_id	Number	The comment ID
text	String	The text of the comment

Success 200

Field	Type	Description
id	Number	The ID of the reply
user_id	Number	The ID of the user who posted the comment.
text	String	The content of the comment
created_at	DateTime	The date and time the reply was created in UTC
files	Array	An array of files attached to the reply
deleted_by	String	The username of the user who deleted the ticket, if it has been deleted. `null` otherwise.
deleted_at	DateTime	A UTC timestamp when the ticket was deleted, if it has been deleted. `null` otherwise.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "user_id": 1,
    "text": "This is my updated comment.",
    "created_at": "2016-05-26 17:41:08",
    "files": [],
    "deleted_by": null,
    "deleted_at": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "text": "The text field is required."
     },
     "status_code": 422
   }
 }

Tickets - Update ticket

Update an existing ticket.

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field	Type	Description
id	Number	The ticket ID
subject optional	String	A subject for the ticket
type optional	String	If this is provided, and it differs from the existing `type`, it will move the ticket to this type. If you are switching a ticket from `internal` to `public`, you must also supply the `inbound_email_account_id` and `email_address` properties. Allowed values: `"internal"`, `"public"`
ticket_group_id optional	Number	A valid ID for a ticket group. A ticket must have at least a group or a responsible user.
category_ids optional	Array	An array of ticket category IDs to assign to this ticket.
user_id optional	Number	A valid responsible user ID. A ticket must have at least a group or a responsible user.
assignee optional	String	The type of entity to assign the ticket to. Public tickets can only be assigned to accounts. Allowed values: `"accounts"`, `"network_sites"`
assignee_id optional	Number	The ID of the assignee to assign this ticket to. If this is set, assignee must be set and vice versa.
due_date optional	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address optional	String	An email address, required if this is a public ticket.
priority optional	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Default value: `4` Allowed values: `1`, `2`, `3`, `4`
open optional	Boolean	Whether the ticket is open or closed. Send `false` to close the ticket, `true` to open it.
child_ticket_ids optional	Array	An array of child ticket IDs of this ticket
inbound_email_account_id optional	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Can only be set on a public ticket.
spam optional	Boolean	Whether or not the ticket is spam
update_child_status optional	Boolean	If this ticket has child tickets, and you wish to update them all with whatever the status is of this ticket, set this to true. For example, if this ticket is closed, or you are closing it, and you want to update all child tickets to closed, set this value to `true`. Default value: `false`

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`, `"network_sites"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply
closed_at	DateTime	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": 3,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": true,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Update ticket

Update an existing ticket.

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field	Type	Description
id	Number	The ticket ID
subject optional	String	A subject for the ticket
ticket_group_id optional	Number	A valid ID for a ticket group. A ticket must have at least a group or a responsible user.
category_ids optional	Array	An array of ticket category IDs to assign to this ticket.
user_id optional	Number	A valid responsible user ID. A ticket must have at least a group or a responsible user.
assignee optional	String	The type of entity to assign the ticket to. Public tickets can only be assigned to accounts. Allowed values: `"accounts"`, `"network_sites"`
assignee_id optional	Number	The ID of the assignee to assign this ticket to. If this is set, assignee must be set and vice versa.
due_date optional	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address optional	String	An email address, required if this is a public ticket.
priority optional	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Default value: `4` Allowed values: `1`, `2`, `3`, `4`
open optional	Boolean	Whether the ticket is open or closed. Send `false` to close the ticket, `true` to open it.
child_ticket_ids optional	Array	An array of child ticket IDs of this ticket
inbound_email_account_id optional	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Can only be set on a public ticket.
spam optional	Boolean	Whether or not the ticket is spam
update_child_status optional	Boolean	If this ticket has child tickets, and you wish to update them all with whatever the status is of this ticket, set this to true. For example, if this ticket is closed, or you are closing it, and you want to update all child tickets to closed, set this value to `true`. Default value: `false`

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`, `"network_sites"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply
closed_at	DateTime	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": 3,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": true,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Update ticket

Update an existing ticket.

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field	Type	Description
id	Number	The ticket ID
subject optional	String	A subject for the ticket
ticket_group_id optional	Number	A valid ID for a ticket group. A ticket must have at least a group or a responsible user.
category_ids optional	Array	An array of ticket category IDs to assign to this ticket.
user_id optional	Number	A valid responsible user ID. A ticket must have at least a group or a responsible user.
assignee optional	String	The type of entity to assign the ticket to. Public tickets can only be assigned to accounts. Allowed values: `"accounts"`
assignee_id optional	Number	The ID of the assignee to assign this ticket to. If this is set, assignee must be set and vice versa.
due_date optional	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address optional	String	An email address, required if this is a public ticket.
priority optional	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Default value: `4` Allowed values: `1`, `2`, `3`, `4`
open optional	Boolean	Whether the ticket is open or closed. Send `false` to close the ticket, `true` to open it.
child_ticket_ids optional	Array	An array of child ticket IDs of this ticket
inbound_email_account_id optional	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Can only be set on a public ticket.
spam optional	Boolean	Whether or not the ticket is spam
update_child_status optional	Boolean	If this ticket has child tickets, and you wish to update them all with whatever the status is of this ticket, set this to true. For example, if this ticket is closed, or you are closing it, and you want to update all child tickets to closed, set this value to `true`. Default value: `false`

Success 200

Field	Type	Description
id	Number	The ID of the ticket.
subject	String	A subject for the ticket.
type	String	The type of ticket.
ticket_group_id	Number	The ticket group for the ticket.
user_id	Number	The responsible user for the ticket.
assignee	String	The type of entity the ticket is assigned to. Allowed values: `"accounts"`
assignee_id	Number	The ID of the assignee that the ticket is assigned to.
due_date	Date	A date in Y-m-d format that dictates when the ticket must be completed by.
email_address	String	An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)
priority	Number	A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical. Allowed values: `1`, `2`, `3`, `4`
category_ids	Array	An array of category IDs for this ticket
open	Boolean	Whether or not the ticket is open
parent_ticket_id	Number	If this ticket is a child ticket, this will be the ID of the parent ticket
inbound_email_account_id	Number	The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.
spam	Boolean	Whether or not the ticket is spam flagged
last_reply_incoming	Boolean	Whether or not the last reply posted to a ticket was an incoming reply
closed_at	DateTime	If the ticket is closed, this is the date and time it was closed in UTC
closed_by_user_id	Number	If the ticket is closed, this is the user ID of the user that closed it
created_at	DateTime	The date and time a ticket was created, in UTC

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": 3,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": true,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Transaction Batches

Transaction_Batches - Create a new transaction batch

Create a new transaction batch. A transaction batch allows you to import multiple transactions in a single call. The transactions will be queued and entered in the background, and any failures will be sent to you as a notification.

https://example.sonar.software/api/v1/financial/transaction_batches

Parameter

Field	Type	Description
name optional	String	A name for the transaction batch
batch_id optional	String	A batch ID. This is not required, but recommended. If you submit a batch ID, then any further imports submitted with the same batch ID will be rejected. This is a safeguard to ensure external systems aren't submitting the same batches multiple times.
transactions	Array	An array of objects, the objects representing transactions to import. See the example below for a visual representation of the structure. The values below this line show the content of each object within this array.
account_id	Integer	An account ID to add a transaction to
service_id	Integer	The service ID to use when adding the transaction
quantity optional	Integer	The quantity to use when running the transaction. This is only valid for recurring and one time services. Default value: `1`
description_override optional	String	If you want the transaction description to be overridden on the invoice, then enter an override string here
amount	Number	An amount to use when adding the transaction. This can only be used when adding adjustment services, and is required if you are adding one. It should be ommitted for other types of services.
override_taxation optional	Boolean	If this is `true`, then any taxes associated with the service referenced by `service_id` will not be applied. Instead, the tax amounts specified in the `tax_transactions` property will be used. If `tax_transactions` is missing or empty, instead, no tax will be applied. Default value: `false`
tax_transactions optional	Array	An array of objects, only used if `override_taxation` is `true`. Each object should have two properties, `description` and `amount`. These amounts will be applied to the service as taxes, with the tax name being the `description` property.

Request-Example:

{
     "name": "My first batch",
     "batch_id": "acme-12345",
     "transactions": [
         {
             "account_id": 3,
             "service_id": 89,
             "quantity": 12,
             "override_taxation": false
         },
         {
             "account_id": 3,
             "service_id": 55,
             "description_override": "After Hours Support",
             "override_taxation": true //Here, no taxes will be applied even if service_id 55 has taxes, because we are overriding taxes and supplying no transactions
         },
         {
             "account_id": 55,
             "service_id": 53,
             "amount": 12.53,
             "description_override": "Custom painting charge",
             "override_taxation": true,
             "tax_transactions": [
                 {
                     "amount": 12.43,
                     "description": "Some tax"
                 }
             ]
         }
     ]
}

Success 200

Field	Type	Description
id	Integer	The ID of the transaction batch.
batch_id	String	The batch ID. If you did not supply one, a random one is generated.
name	String	The name of the transaction batch
created_at	DateTime	The date and time the batch was created, in UTC.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "batch_id": "acme-12345",
    "name": "My first batch",
    "created_at": "2016-11-15 20:16:39"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "batch_id": "The batch id must be unique."
     },
     "status_code": 422
   }
 }

Transaction_Batches - Create a new transaction batch

https://example.sonar.software/api/v1/financial/transaction_batches

Parameter

Field	Type	Description
name optional	String	A name for the transaction batch
batch_id optional	String	A batch ID. This is not required, but recommended. If you submit a batch ID, then any further imports submitted with the same batch ID will be rejected. This is a safeguard to ensure external systems aren't submitting the same batches multiple times.
transactions	Array	An array of objects, the objects representing transactions to import. See the example below for a visual representation of the structure. The values below this line show the content of each object within this array.
account_id	Integer	An account ID to add a transaction to
service_id	Integer	The service ID to use when adding the transaction
quantity optional	Integer	The quantity to use when running the transaction. This is only valid for recurring and one time services. Default value: `1`
description_override optional	String	If you want the transaction description to be overridden on the invoice, then enter an override string here
amount	Number	An amount to use when adding the transaction. This can only be used when adding adjustment services, and is required if you are adding one. It should be ommitted for other types of services.

Request-Example:

{
    "name": "My first batch",
    "batch_id": "acme-12345",
    "transactions": [
        {
            "account_id": 3,
            "service_id": 89,
            "quantity": 12
        },
        {
            "account_id": 3,
            "service_id": 55,
            "description_override": "After Hours Support"
        },
        {
            "account_id": 55,
            "service_id": 53,
            "amount": 12.53,
            "description_override": "Custom painting charge"
        }
    ]
}

Success 200

Field	Type	Description
id	Integer	The ID of the transaction batch.
batch_id	String	The batch ID. If you did not supply one, a random one is generated.
name	String	The name of the transaction batch
created_at	DateTime	The date and time the batch was created, in UTC.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "batch_id": "acme-12345",
    "name": "My first batch",
    "created_at": "2016-11-15 20:16:39"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "batch_id": "The batch id must be unique."
     },
     "status_code": 422
   }
 }

Usage Based Billing Policies

Usage_Based_Billing_Policies - Create a new usage based billing free period

Create a new usage based billing free period.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods

Parameter

Field	Type	Description
usage_based_billing_policy_id	Number	The ID of the usage based billing policy.
day	Number	The day of the week of the free period, where 0 is Sunday and 6 is Saturday
start	Time	The start of the free period in HH:MM:SS
end	Time	The end of the free period in HH:MM:SS

Success 200

Field	Type	Description
id	Number	The ID of the usage based billing free period.
day	Number	The day of the week of the free period, where 0 is Sunday and 6 is Saturday
start	Time	The start of the free period in HH:MM:SS
end	Time	The end of the free period in HH:MM:SS

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "day": 0,
    "start": "00:00:00",
    "end": "02:30:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": "This free period overlaps another defined free period from 09:00:00 to 21:32:00.",
     "status_code": 422
   }
 }

Usage_Based_Billing_Policies - Create a new usage based billing policy

Create a new usage based billing policy.

https://example.sonar.software/api/v1/system/usage_based_billing_policies

Parameter

Field	Type	Description
description	String	A description of the policy.
cap_in_gigabytes	Number	The cap on the policy, in gigabytes.
rollover_enabled	Boolean	If rollover is enabled on this policy.
rollover_expiration_enabled	Boolean	If rollover data expires
rollover_expires_after_months optional	Number	If `rollover_expiration_enabled` is true, then any unused data rolled over expires after this many months. This is required if `rollover_expiration_enabled` is true!
assess_charges_at_end_of_billing_period	Boolean	If this is true, then any data usage over `cap_in_gigabytes` will be charged at the rates defined in the overage service linked as `service_id`
allow_user_to_purchase_capacity	Boolean	If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as `service_id`
service_id optional	Number	If either `assess_charges_at_end_of_billing_period` or `allow_user_to_purchase_capacity` are true, then this is the ID of the overage service used to determine the rates for those functions. This is required if either of the aforementioned properties are true!

Success 200

Field	Type	Description
id	Number	The ID of the usage based billing policy.
description	String	A description of the policy.
cap_in_gigabytes	Number	The cap on the policy, in gigabytes.
rollover_enabled	Boolean	If rollover is enabled on this policy.
rollover_expiration_enabled	Boolean	If rollover data expires
rollover_expires_after_months	Number	If `rollover_expiration_enabled` is true, then any unused data rolled over expires after this many months
assess_charges_at_end_of_billing_period	Boolean	If this is true, then any data usage over `cap_in_gigabytes` will be charged at the rates defined in the overage service linked as `service_id`
allow_user_to_purchase_capacity	Boolean	If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as `service_id`
service_id	Number	If either `assess_charges_at_end_of_billing_period` or `allow_user_to_purchase_capacity` are true, then this is the ID of the overage service used to determine the rates for those functions.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 9,
    "description": "Test 123",
    "cap_in_gigabytes": 150,
    "rollover_enabled": false,
    "rollover_expiration_enabled": false,
    "rollover_expires_after_months": 0,
    "assess_charges_at_end_of_billing_period": false,
    "allow_user_to_purchase_capacity": false,
    "service_id": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "description": "The description must be unique."
     },
     "status_code": 422
   }
 }

Usage_Based_Billing_Policies - Delete a usage based billing free period

Delete a usage based billing free period

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods/:id

Parameter

Field	Type	Description
usage_based_billing_policy_id	Number	The ID of the usage based billing policy
id	Number	The ID of the usage based billing free period

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the usage based billing free period could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Usage based billing free period does not exist.",
         "status_code": 404
     }
 }

Usage_Based_Billing_Policies - Delete a usage based billing policy

Delete a usage based billing policy. If this is currently on any services, it will be removed from the services, and all users with those services will no longer have a usage cap.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:id

Parameter

Field	Type	Description
id	Number	The ID of the usage based billing policy

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the usage based billing policy could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Usage based billing policy does not exist.",
         "status_code": 404
     }
 }

Usage_Based_Billing_Policies - Get all usage based billing free periods

Get all usage based billing free periods for a specific policy.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods

Parameter

Field	Type	Description
usage_based_billing_policy_id	Number	The ID of the usage based billing policy the free period is attached to
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the usage based billing free period.
day	Number	The day of the week of the free period, where 0 is Sunday and 6 is Saturday
start	Time	The start of the free period in HH:MM:SS
end	Time	The end of the free period in HH:MM:SS

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "day": 0,
      "start": "00:00:00",
      "end": "02:30:00"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Usage_Based_Billing_Policies - Get all usage based billing policies

Get all usage based billing policies

https://example.sonar.software/api/v1/system/usage_based_billing_policies

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the usage based billing policy.
description	String	A description of the policy.
cap_in_gigabytes	Number	The cap on the policy, in gigabytes.
rollover_enabled	Boolean	If rollover is enabled on this policy.
rollover_expiration_enabled	Boolean	If rollover data expires
rollover_expires_after_months	Number	If `rollover_expiration_enabled` is true, then any unused data rolled over expires after this many months
assess_charges_at_end_of_billing_period	Boolean	If this is true, then any data usage over `cap_in_gigabytes` will be charged at the rates defined in the overage service linked as `service_id`
allow_user_to_purchase_capacity	Boolean	If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as `service_id`
service_id	Number	If either `assess_charges_at_end_of_billing_period` or `allow_user_to_purchase_capacity` are true, then this is the ID of the overage service used to determine the rates for those functions.

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "description": "No Rollover",
      "cap_in_gigabytes": 5,
      "rollover_enabled": false,
      "rollover_expiration_enabled": false,
      "rollover_expires_after_months": 0,
      "assess_charges_at_end_of_billing_period": false,
      "allow_user_to_purchase_capacity": false,
      "service_id": null
    },
    {
      "id": 3,
      "description": "Rollover No Expiration",
      "cap_in_gigabytes": 1,
      "rollover_enabled": true,
      "rollover_expiration_enabled": false,
      "rollover_expires_after_months": 0,
      "assess_charges_at_end_of_billing_period": false,
      "allow_user_to_purchase_capacity": false,
      "service_id": null
    },
    {
      "id": 2,
      "description": "Rollover 3 month expiration",
      "cap_in_gigabytes": 1,
      "rollover_enabled": true,
      "rollover_expiration_enabled": true,
      "rollover_expires_after_months": 3,
      "assess_charges_at_end_of_billing_period": false,
      "allow_user_to_purchase_capacity": true,
      "service_id": 15
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Usage_Based_Billing_Policies - Get an individual usage based billing free period

Get an individual usage based billing free period

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods/:id

Parameter

Field	Type	Description
usage_based_billing_policy_id	Number	The ID of the usage based billing policy the free period is attached to
id	Number	The ID of the usage based billing free period

Success 200

Field	Type	Description
id	Number	The ID of the usage based billing free period.
day	Number	The day of the week of the free period, where 0 is Sunday and 6 is Saturday
start	Time	The start of the free period in HH:MM:SS
end	Time	The end of the free period in HH:MM:SS

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "day": 0,
    "start": "00:00:00",
    "end": "02:30:00"
  }
}

Usage_Based_Billing_Policies - Get an individual usage based billing policy

Get an individual usage based billing policy

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:id

Parameter

Field	Type	Description
id	Number	The ID of the usage based billing policy

Success 200

Field	Type	Description
id	Number	The ID of the usage based billing policy.
description	String	A description of the policy.
cap_in_gigabytes	Number	The cap on the policy, in gigabytes.
rollover_enabled	Boolean	If rollover is enabled on this policy.
rollover_expiration_enabled	Boolean	If rollover data expires
rollover_expires_after_months	Number	If `rollover_expiration_enabled` is true, then any unused data rolled over expires after this many months
assess_charges_at_end_of_billing_period	Boolean	If this is true, then any data usage over `cap_in_gigabytes` will be charged at the rates defined in the overage service linked as `service_id`
allow_user_to_purchase_capacity	Boolean	If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as `service_id`
service_id	Number	If either `assess_charges_at_end_of_billing_period` or `allow_user_to_purchase_capacity` are true, then this is the ID of the overage service used to determine the rates for those functions.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "description": "Rollover 3 month expiration",
    "cap_in_gigabytes": 1,
    "rollover_enabled": true,
    "rollover_expiration_enabled": true,
    "rollover_expires_after_months": 3,
    "assess_charges_at_end_of_billing_period": false,
    "allow_user_to_purchase_capacity": true,
    "service_id": 15
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Usage_Based_Billing_Policies - Update usage based billing free period

Update an existing usage based billing free period.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods/:id

Parameter

Field	Type	Description
usage_based_billing_policy_id	Number	The ID of the usage based billing policy.
id	Number	The ID of the usage based billing free period
day optional	Number	The day of the week of the free period, where 0 is Sunday and 6 is Saturday
start optional	Time	The start of the free period in HH:MM:SS
end optional	Time	The end of the free period in HH:MM:SS

Success 200

Field	Type	Description
id	Number	The ID of the usage based billing free period.
day	Number	The day of the week of the free period, where 0 is Sunday and 6 is Saturday
start	Time	The start of the free period in HH:MM:SS
end	Time	The end of the free period in HH:MM:SS

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "day": 0,
    "start": "00:00:00",
    "end": "02:30:00"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Usage_Based_Billing_Policies - Update usage based billing policy

Update an existing usage based billing policy.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:id

Parameter

Field	Type	Description
id	Number	The usage based billing policy ID
description	String	A description of the policy.
cap_in_gigabytes	Number	The cap on the policy, in gigabytes.
rollover_enabled	Boolean	If rollover is enabled on this policy.
rollover_expiration_enabled	Boolean	If rollover data expires
rollover_expires_after_months optional	Number	If `rollover_expiration_enabled` is true, then any unused data rolled over expires after this many months. This is required if `rollover_expiration_enabled` is true!
assess_charges_at_end_of_billing_period	Boolean	If this is true, then any data usage over `cap_in_gigabytes` will be charged at the rates defined in the overage service linked as `service_id`
allow_user_to_purchase_capacity	Boolean	If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as `service_id`
service_id optional	Number	If either `assess_charges_at_end_of_billing_period` or `allow_user_to_purchase_capacity` are true, then this is the ID of the overage service used to determine the rates for those functions. This is required if either of the aforementioned properties are true!

Success 200

Field	Type	Description
id	Number	The ID of the usage based billing policy.
description	String	A description of the policy.
cap_in_gigabytes	Number	The cap on the policy, in gigabytes.
rollover_enabled	Boolean	If rollover is enabled on this policy.
rollover_expiration_enabled	Boolean	If rollover data expires
rollover_expires_after_months	Number	If `rollover_expiration_enabled` is true, then any unused data rolled over expires after this many months
assess_charges_at_end_of_billing_period	Boolean	If this is true, then any data usage over `cap_in_gigabytes` will be charged at the rates defined in the overage service linked as `service_id`
allow_user_to_purchase_capacity	Boolean	If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as `service_id`
service_id	Number	If either `assess_charges_at_end_of_billing_period` or `allow_user_to_purchase_capacity` are true, then this is the ID of the overage service used to determine the rates for those functions.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 9,
    "description": "Test 123",
    "cap_in_gigabytes": 150,
    "rollover_enabled": false,
    "rollover_expiration_enabled": false,
    "rollover_expires_after_months": 0,
    "assess_charges_at_end_of_billing_period": false,
    "allow_user_to_purchase_capacity": false,
    "service_id": null
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Users

Users - Create user

Create a new user.

https://example.sonar.software/api/v1/users

Parameter

Field	Type	Description
username	String	A unique username for the user
password	String	A plain text password
name	String	The name of the user
public_name	String	The public name of the user
role_id	Number	The ID of the role for this user. These can be loaded from the roles endpoint.
email_address	String	The email address for the user
mobile_number optional	Number	The mobile telephone number for the user

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
public_name	String	The public name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
mobile_number	Number	The mobile telephone number for the user

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 15,
        "username": "Hansolo",
        "name": "Han Solo",
        "public_name": "Han S.",
        "locale": "en",
        "role_id": 3,
        "email_address": "test@example.com",
        "mobile_number": null
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Create user

Create a new user.

https://example.sonar.software/api/v1/users

Parameter

Field	Type	Description
username	String	A unique username for the user
password	String	A plain text password
name	String	The name of the user
public_name	String	The public name of the user
role_id	Number	The ID of the role for this user. These can be loaded from the roles endpoint.
email_address	String	The email address for the user

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "John Doe",
        "public_name": "John D",
        "role_id": 1,
        "email_address": "John_Doe@example.com"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Create user

Create a new user.

https://example.sonar.software/api/v1/users

Parameter

Field	Type	Description
username	String	A unique username for the user
password	String	A plain text password
name	String	The name of the user
role_id	Number	The ID of the role for this user. These can be loaded from the roles endpoint.
email_address	String	The email address for the user
locale optional	String	A valid locale (language) for the user. You can get a list of valid locales from /_data/locales. Default value: `System Default`

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
locale	String	A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "John Doe",
        "role_id": 1,
        "email_address": "John_Doe@example.com",
        "locale": "en"
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Create user

Create a new user.

https://example.sonar.software/api/v1/users

Parameter

Field	Type	Description
username	String	A unique username for the user
password	String	A plain text password
name	String	The name of the user
role_id	Number	The ID of the role for this user. These can be loaded from the roles endpoint.
email_address	String	The email address for the user
api	Boolean	Whether or not the user has API access

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
api	Boolean	Whether or not the user has API access

Success-Response:

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "John Doe",
        "role_id": 1,
        "email_address": "John_Doe@example.com",
        "api": true
   }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Delete user

Delete a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field	Type	Description
id	Number	The ID of the user

Success 200

Field	Type	Description
message	String	A message stating that the deletion was successful.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "message": "User deleted"
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the user could not be deleted
status_code	Number	4xx

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": "You cannot delete the last user with super admin privileges.",
         "status_code": 422
     }
 }

Users - Get all users

Get a list of users from within Sonar.

https://example.sonar.software/api/v1/users/

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
public_name	String	The public name of the user
locale	String	The users preferred locale
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
mobile_number	Number	The mobile telephone number for the user

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "public_name": "Han S.",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com",
            "mobile_number": "4148675309"
        },
        {
            "id": 11,
            "username": "admin",
            "name": "John Doe the Third",
            "public_name": "Johnny D",
            "locale": "en",
            "role_id": 1,
            "email_address": "simon@sonar.software",
            "mobile_number": null
        }
    ]
}

Users - Get all users

Get a list of users from within Sonar.

https://example.sonar.software/api/v1/users/

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
public_name	String	The public name of the user
locale	String	The users preferred locale
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "public_name": "Han S.",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com"
        },
        {
            "id": 11,
            "username": "admin",
            "name": "John Doe the Third",
            "public_name": "Johnny D",
            "locale": "en",
            "role_id": 1,
            "email_address": "simon@sonar.software"
        }
    ]
}

Users - Get all users

Get a list of users from within Sonar.

https://example.sonar.software/api/v1/users/

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
locale	String	The users preferred locale
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "role_id": 3,
            "email_address": "test@example.com",
            "locale": "en"
        },
        {
            "id": 11,
            "username": "admin",
            "name": "John Doe the Third",
            "role_id": 1,
            "email_address": "simon@sonar.software",
            "locale": "en"
        }
    ]
}

Users - Get all users

Get a list of users from within Sonar.

https://example.sonar.software/api/v1/users/

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
locale	String	The users preferred locale
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
api	Boolean	Whether or not the user has API access

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com",
            "api": true
        },
        {
            "id": 11,
            "username": "admin",
            "name": "John Doe the Third",
            "locale": "en",
            "role_id": 1,
            "email_address": "simon@sonar.software",
            "api": true
        }
    ]
}

Users - Get individual user

Get data on an Get individual user.

https://example.sonar.software/api/v1/users/:id

Example usage:

curl -i https://example.sonar.software/api/v1/users/15

Parameter

Field	Type	Description
id	Number	The id of the user

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
public_name	String	The public name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
mobile_number	Number	The mobile telephone number for the user

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "public_name": "Han S.",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com",
            "mobile_number": null
        }
   ]
}

Users - Get individual user

Get data on an Get individual user.

https://example.sonar.software/api/v1/users/:id

Example usage:

curl -i https://example.sonar.software/api/v1/users/15

Parameter

Field	Type	Description
id	Number	The id of the user

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
public_name	String	The public name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "public_name": "Han S.",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com"
        }
   ]
}

Users - Get individual user

Get data on an Get individual user.

https://example.sonar.software/api/v1/users/:id

Example usage:

curl -i https://example.sonar.software/api/v1/users/15

Parameter

Field	Type	Description
id	Number	The id of the user

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
locale	String	A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "role_id": 3,
            "email_address": "test@example.com",
            "locale": "en"
        }
   ]
}

Users - Get individual user

Get data on an Get individual user.

https://example.sonar.software/api/v1/users/:id

Example usage:

curl -i https://example.sonar.software/api/v1/users/15

Parameter

Field	Type	Description
id	Number	The id of the user

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
api	Boolean	Whether or not the user has API access

Success-Response:

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com",
            "api": true
        }
   ]
}

Users - Update user

Update a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field	Type	Description
id	Number	The ID of the user
username optional	String	The username of the user
password optional	String	A plain text password for the user
name optional	String	The name of the user
public_name optional	String	The public name of the user
role_id optional	Number	The ID of the role for this user. These can be loaded from the roles endpoint.
email_address optional	String	The email address for the user
mobile_number optional	Number	The mobile telephone number for the user

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
public_name	String	The public name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
mobile_number	Number	The mobile telephone number for the user

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "Jonathan Doe",
        "public_name": "John D",
        "role_id": 1,
        "email_address": "Johnathan_Doe@example.com",
        "mobile_number": null
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Update user

Update a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field	Type	Description
id	Number	The ID of the user
username optional	String	The username of the user
password optional	String	A plain text password for the user
name optional	String	The name of the user
public_name optional	String	The public name of the user
role_id optional	Number	The ID of the role for this user. These can be loaded from the roles endpoint.
email_address optional	String	The email address for the user

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
public_name	String	The public name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "Jonathan Doe",
        "public_name": "John D",
        "role_id": 1,
        "email_address": "Johnathan_Doe@example.com"
    }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Update user

Update a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field	Type	Description
id	Number	The ID of the user
username optional	String	The username of the user
password optional	String	A plain text password for the user
name optional	String	The name of the user
role_id optional	Number	The ID of the role for this user. These can be loaded from the roles endpoint.
email_address optional	String	The email address for the user
locale optional	String	A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.
must_reset optional	Boolean	Set this to true to force the user to reset their password on next login.

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
locale	String	A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "first_name": "Jonathan Doe",
        "role_id": 1,
        "email_address": "Johnathan_Doe@example.com",
        "locale": "en"
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Update user

Update a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field	Type	Description
id	Number	The ID of the user
username optional	String	The username of the user
password optional	String	A plain text password for the user
name optional	String	The name of the user
role_id optional	Number	The ID of the role for this user. These can be loaded from the roles endpoint.
email_address optional	String	The email address for the user
api	Boolean	Whether or not the user has API access

Success 200

Field	Type	Description
id	Number	The internal id of the user
username	String	The username of the user
name	String	The name of the user
role_id	Number	The ID associated with the role that the user has
email_address	String	The email address associated with the user
api	Boolean	Whether or not the user has API access

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "first_name": "Jonathan Doe",
        "role_id": 1,
        "email_address": "Johnathan_Doe@example.com",
        "api": true
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Voice Providers

Voice_Providers - Create a new voice provider

Create a new voice provider.

https://example.sonar.software/api/v1/system/voice/voice_providers

Parameter

Field	Type	Description
name	String	A name for the voice provider

Success 200

Field	Type	Description
id	Number	The ID of the voice provider.
name	String	The name of the voice provider

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Flowroute",
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	422

Error-Response:

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Voice_Providers - Delete a voice provider

Delete a voice provider

https://example.sonar.software/api/v1/system/voice/voice_providers/:id

Parameter

Field	Type	Description
id	Number	The ID of the voice provider

Success 200

Field	Type	Description
success	Boolean	Will be true if deletion succeeded.

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name	Type	Description
message	String	A reason as to why the voice provider could not be deleted
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Voice provider does not exist.",
         "status_code": 404
     }
 }

Voice_Providers - Get all voice providers

Get all voice providers

https://example.sonar.software/api/v1/system/voice/voice_providers

Parameter

Field	Type	Description
limit optional	Number	The number of entries to return
page optional	Number	The page of results to return

Success 200

Field	Type	Description
id	Number	The ID of the voice provider.
name	String	The name of the voice provider

Success-Response:

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Flowroute"
    },
    {
      "id": 1,
      "name": "Vitelity"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Voice_Providers - Get an individual voice provider

Get an individual voice provider

https://example.sonar.software/api/v1/system/voice/voice_providers/:id

Parameter

Field	Type	Description
id	Number	The ID of the voice provider

Success 200

Field	Type	Description
id	Number	The ID of the voice provider.
name	String	The name of the voice provider.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Flowroute"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	404

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Voice_Providers - Import a rate deck

Import a rate deck for a voice provider. Please note that hitting this endpoint will delete all existing rates for this provider before beginning new import. In case of a failure, your rates may still be removed, so please ensure you successfully complete and verify a rate deck import when using this endpoint! It may also take some time for a large rate deck to be imported - importing 100,000 rates here can take upwards of 60 seconds. Please ensure you have a sufficiently large timeout set in your script/client when performing this import.

https://example.sonar.software/api/v1/system/voice/voice_providers/:id/import_rates

Example

{
      "minimum_rate": 0.01,
      "percentage_increase": 40,
      "rates": [
             {
                    "name": "ANDORRA",
                    "prefix": "3763",
                    "rate": 0.30786
             },
             {
                    "name": "ANDORRA - MOBILE",
                    "prefix": "3764",
                    "rate": 0.307485
             }
      ]
}

Parameter

Field	Type	Description
id	Number	The ID of the voice provider
rates	Array	An array of names, prefixes, and rates. The array should contain multiple objects with a `name` property that explains the rate, a `prefix` property that contains the dialed number prefix, and a `rate` property that represents the rate to call that prefix, per minute, in cents (or whatever the smallest currency denomination you use is.) The rate can be represented as a fraction (float.) Example shown below.
minimum_rate	Number	The minimum rate for calls, per minute. You can use this to override the percentage increase in the case where you want a minimum rate that may be higher than the percentage increase for some rates.
percentage_increase	Number	A percentage increase, between 0 and 100. This will be used to increase the rate in the `rates` array by this percentage. If the percentage increase is less than `minimum_rate`, then the minimum rate will be used instead.

Success 200

Field	Type	Description
success	Boolean	Will be true if import succeeded.
errors	Array	If the import succeeded, but some errors were found in the import, they will be enumerated here.

Success-Response:

HTTP/1.1 200 OK
{
  "data": {
    "success": true,
    "errors": [
      "Line 3 was skipped as it had a rate or prefix that was not numeric."
    ]
  }
}

Error 4xx

Name	Type	Description
message	String	A list of errors that occurred during import. If some lines fail, the remainder will still be imported.
status_code	Number	4x

Error-Response:

HTTP/1.1 404
 {
     "error": {
         "message": "Voice provider does not exist.",
         "status_code": 404
     }
 }

Voice_Providers - Update voice provider

Update an existing voice provider.

https://example.sonar.software/api/v1/system/voice/voice_providers/:id

Parameter

Field	Type	Description
id	Number	The voice provider ID
name optional	String	The name of the voice provider

Success 200

Field	Type	Description
id	Number	The ID of the voice provider.
name	String	The name of the voice provider.

Success-Response:

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Fowroute"
  }
}

Error 4xx

Name	Type	Description
message	String	A list of validation errors
status_code	Number	4xx

Error-Response:

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Generated with apidoc 0.16.1 - 2021-09-16T18:14:42.498Z